@ictechgy/context-guard 0.4.15 → 0.5.1

package/plugins/context-guard/bin/context-guard-setup

@@ -10,8 +10,10 @@ from __future__ import annotations
 import argparse
 import copy
 import datetime as _dt
+import hashlib
 import json
 import os
+import pwd
 import re
 import selectors
 import shlex
@@ -21,6 +23,7 @@ import stat
 import subprocess
 import sys
 import time
+import types
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
@@ -46,8 +49,6 @@ RECOMMENDED_DENIES = [
     "Read(./vendor/**)",
     "Read(./.context-guard/**)",
     "Read(./.claude-token-optimizer/**)",
-    "Read(./.env)",
-    "Read(./.env.*)",
     "Read(./.npmrc)",
     "Read(./.pypirc)",
     "Read(./.netrc)",
@@ -57,11 +58,26 @@ RECOMMENDED_DENIES = [
     "Read(~/.kube/**)",
     "Read(~/.docker/**)",
 ]
+PRODUCT_OWNED_ENV_READ_DENIES = frozenset({
+    "Read(./.env)",
+    "Read(./.env.*)",
+})
 HELPER_STATUSLINE = "context-guard-statusline-merged"
+HELPER_STATUSLINE_PLAIN = "context-guard-statusline"
 HELPER_REWRITE_BASH = "context-guard-rewrite-bash"
 HELPER_GUARD_READ = "context-guard-guard-read"
 HELPER_FAILED_NUDGE = "context-guard-failed-nudge"
 HELPER_DIET = "context-guard-diet"
+ROOT_PACKAGE_NAME = "@ictechgy/context-guard"
+RECEIPT_PACKAGE_NAME = "@ictechgy/context-guard-receipt"
+_BASH_REFERENCE_UNAVAILABLE = (
+    "bash_reference_v1 reference unavailable"
+)
+_BASH_REFERENCE_RECOVERY = (
+    "repair or reinstall the exact paired npm packages in the target project, "
+    "ensure a trusted system Node interpreter is available, then rerun setup"
+)
+BASH_REFERENCE_POLICY_MAX_BYTES = 512 * 1024
 HELPER_EQUIVALENT_BASENAMES = {
     "context-guard-rewrite-bash": {
         "context-guard-rewrite-bash",
@@ -96,6 +112,33 @@ DEFAULT_POST_SETUP_SCAN_TOP = 5
 POST_SETUP_SCAN_TIMEOUT_SECONDS = 20
 PATH_HELPER_PROBE_TIMEOUT_SECONDS = 5
 PATH_HELPER_PROBE_MAX_OUTPUT_BYTES = 4096
+ISOLATED_RUNTIME_PATH = os.defpath
+READ_GUARD_BEHAVIOR_ENV = (
+    "CONTEXT_GUARD_READ_GUARD",
+    "CLAUDE_TOKEN_READ_GUARD",
+    "CONTEXT_GUARD_READ_GUARD_MAX_BYTES",
+    "CLAUDE_TOKEN_READ_GUARD_MAX_BYTES",
+    "CONTEXT_GUARD_READ_GUARD_MAX_LINES",
+    "CLAUDE_TOKEN_READ_GUARD_MAX_LINES",
+    "CONTEXT_GUARD_READ_GUARD_PROOF_BYTES",
+    "CLAUDE_TOKEN_READ_GUARD_PROOF_BYTES",
+)
+REWRITE_BEHAVIOR_ENV = (
+    "CONTEXT_GUARD_SANITIZER_FAIL_OPEN",
+    "CLAUDE_TOKEN_SANITIZER_FAIL_OPEN",
+)
+STATUSLINE_BEHAVIOR_ENV = (
+    "CONTEXT_GUARD_STATUSLINE_INPUT_MAX_BYTES",
+    "CLAUDE_TOKEN_STATUSLINE_INPUT_MAX_BYTES",
+    "CONTEXT_GUARD_STATUSLINE_CTX_WARN",
+    "CLAUDE_TOKEN_STATUSLINE_CTX_WARN",
+    "CONTEXT_GUARD_STATUSLINE_CACHE_TTL_SECONDS",
+)
+HOMEBREW_NODE_CANDIDATES = (
+    Path("/opt/homebrew/bin/node"),
+    Path("/usr/local/bin/node"),
+)
+BEHAVIOR_ENV_VALUE_RE = re.compile(r"^[A-Za-z0-9.+_-]{1,64}$")
 PRIVATE_DIR_MODE = stat.S_IRWXU
 ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
     "tmp": Path("/private/tmp"),
@@ -108,6 +151,8 @@ class Choices:
     denies: bool = True
     statusline: bool = True
     bash_hook: bool = True
+    # Provider-visible receipt handles are an explicit, default-off choice.
+    bash_reference_v1: bool = False
     read_guard: bool = True
     model_defaults: bool = True
     # 동일 Bash 명령이 두 번 연속 실패하면 /clear 권유 — recommended setup 기본 ON.
@@ -165,14 +210,19 @@ class SetupResult:
 # - native-skill / report-only agents are never written to; they are reported.
 # It never sends work to external providers and never promises token/cost savings.
 
-ADAPTER_RULE_BLOCK_BEGIN = "<!-- contextguard:begin -->"
-ADAPTER_RULE_BLOCK_END = "<!-- contextguard:end -->"
+LEGACY_ADAPTER_RULE_BLOCK_BEGIN = "<!-- contextguard:begin -->"
+LEGACY_ADAPTER_RULE_BLOCK_END = "<!-- contextguard:end -->"
+ADAPTER_RULE_BLOCK_BEGIN = "<!-- BEGIN context-guard:repo-rules version=1 -->"
+ADAPTER_RULE_BLOCK_END = "<!-- END context-guard:repo-rules -->"
 CODEX_SKILL_REL = ".agents/skills/context-guard/SKILL.md"
-CODEX_SKILL_MARKER_BEGIN = "<!-- contextguard:codex-skill:begin -->"
-CODEX_SKILL_MARKER_END = "<!-- contextguard:codex-skill:end -->"
+LEGACY_CODEX_SKILL_MARKER_BEGIN = "<!-- contextguard:codex-skill:begin -->"
+LEGACY_CODEX_SKILL_MARKER_END = "<!-- contextguard:codex-skill:end -->"
+CODEX_SKILL_MARKER_BEGIN = "<!-- BEGIN context-guard:codex-skill version=1 -->"
+CODEX_SKILL_MARKER_END = "<!-- END context-guard:codex-skill -->"
 BRIEF_MODE_LEVELS = ("lite", "standard", "ultra")
 BRIEF_MODE_OFF = "off"
 BRIEF_MODE_CHOICES = (*BRIEF_MODE_LEVELS, BRIEF_MODE_OFF)
+NARRATION_MODE_CHOICES = ("quiet", "default")
 BRIEF_MODE_BLOCK_END = "<!-- END context-guard:brief-mode -->"
 BRIEF_MODE_BEGIN_RE = re.compile(
     r"<!-- BEGIN context-guard:brief-mode level=(?P<level>[a-z]+) version=1 -->"
@@ -186,6 +236,214 @@ BRIEF_MODE_BLOCK_RE = re.compile(
     re.DOTALL,
 )
 
+LEGACY_REPO_RULE_MARKER_BEGIN = LEGACY_ADAPTER_RULE_BLOCK_BEGIN.encode("ascii")
+LEGACY_REPO_RULE_MARKER_END = LEGACY_ADAPTER_RULE_BLOCK_END.encode("ascii")
+REPO_RULE_MARKER_V1_BEGIN = ADAPTER_RULE_BLOCK_BEGIN.encode("ascii")
+REPO_RULE_MARKER_V1_END = ADAPTER_RULE_BLOCK_END.encode("ascii")
+LEGACY_CODEX_SKILL_MARKER_V0_BEGIN = LEGACY_CODEX_SKILL_MARKER_BEGIN.encode("ascii")
+LEGACY_CODEX_SKILL_MARKER_V0_END = LEGACY_CODEX_SKILL_MARKER_END.encode("ascii")
+CODEX_SKILL_MARKER_V1_BEGIN = CODEX_SKILL_MARKER_BEGIN.encode("ascii")
+CODEX_SKILL_MARKER_V1_END = CODEX_SKILL_MARKER_END.encode("ascii")
+BRIEF_MODE_MARKER_END = BRIEF_MODE_BLOCK_END.encode("ascii")
+NARRATION_MODE_MARKER_BEGIN = b"<!-- BEGIN context-guard:narration-mode mode=quiet version=1 -->"
+NARRATION_MODE_MARKER_END = b"<!-- END context-guard:narration-mode -->"
+
+
+@dataclass(frozen=True)
+class ManagedMarker:
+    kind: str
+    version: int
+    begin: bytes
+    end: bytes
+    variant: str | None = None
+
+
+MANAGED_MARKERS = (
+    ManagedMarker(
+        "repo-rules",
+        0,
+        LEGACY_REPO_RULE_MARKER_BEGIN,
+        LEGACY_REPO_RULE_MARKER_END,
+        "legacy",
+    ),
+    ManagedMarker(
+        "repo-rules",
+        1,
+        REPO_RULE_MARKER_V1_BEGIN,
+        REPO_RULE_MARKER_V1_END,
+    ),
+    ManagedMarker(
+        "codex-skill",
+        0,
+        LEGACY_CODEX_SKILL_MARKER_V0_BEGIN,
+        LEGACY_CODEX_SKILL_MARKER_V0_END,
+        "legacy",
+    ),
+    ManagedMarker(
+        "codex-skill",
+        1,
+        CODEX_SKILL_MARKER_V1_BEGIN,
+        CODEX_SKILL_MARKER_V1_END,
+    ),
+    *(
+        ManagedMarker(
+            "brief-mode",
+            1,
+            f"<!-- BEGIN context-guard:brief-mode level={level} version=1 -->".encode("ascii"),
+            BRIEF_MODE_MARKER_END,
+            level,
+        )
+        for level in BRIEF_MODE_LEVELS
+    ),
+    ManagedMarker(
+        "narration-mode",
+        1,
+        NARRATION_MODE_MARKER_BEGIN,
+        NARRATION_MODE_MARKER_END,
+        "quiet",
+    ),
+)
+_MANAGED_BEGIN_MARKERS = {marker.begin: marker for marker in MANAGED_MARKERS}
+_MANAGED_END_MARKERS: dict[bytes, tuple[ManagedMarker, ...]] = {}
+for _marker in MANAGED_MARKERS:
+    _MANAGED_END_MARKERS[_marker.end] = (*_MANAGED_END_MARKERS.get(_marker.end, ()), _marker)
+
+
+@dataclass(frozen=True)
+class ManagedSpan:
+    kind: str
+    version: int
+    variant: str | None
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
+class ManagedParseResult:
+    status: str
+    spans: tuple[ManagedSpan, ...] = ()
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class ManagedFileSnapshot:
+    data: bytes | None
+    metadata: tuple[int, int, int, int, int] | None
+
+
+class ManagedFileConflictError(OSError):
+    """Raised when a managed target no longer matches its planned snapshot."""
+
+
+def _iter_binary_lines(data: bytes):
+    offset = 0
+    while offset < len(data):
+        newline = data.find(b"\n", offset)
+        if newline < 0:
+            yield offset, len(data), data[offset:], b""
+            return
+        end = newline + 1
+        if newline > offset and data[newline - 1 : newline] == b"\r":
+            content, ending = data[offset : newline - 1], b"\r\n"
+        else:
+            content, ending = data[offset:newline], b"\n"
+        yield offset, end, content, ending
+        offset = end
+
+
+def _fence_open(content: bytes) -> tuple[int, int] | None:
+    match = re.match(rb"^ {0,3}(`{3,}|~{3,}).*$", content)
+    if not match:
+        return None
+    run = match.group(1)
+    return run[0], len(run)
+
+
+def _fence_close(content: bytes, fence: tuple[int, int]) -> bool:
+    char, minimum = fence
+    match = re.match(rb"^ {0,3}([`~]+) *$", content)
+    if not match:
+        return False
+    run = match.group(1)
+    return bool(run and run[0] == char and len(run) >= minimum and all(byte == char for byte in run))
+
+
+def _looks_like_contextguard_marker(content: bytes) -> bool:
+    lowered = content.lstrip(b" \t").lower()
+    return (
+        lowered.startswith(b"<!--")
+        and b"-->" in lowered
+        and (b"contextguard:" in lowered or b"context-guard:" in lowered)
+    )
+
+
+def _scan_managed_spans(data: bytes) -> ManagedParseResult:
+    spans: list[ManagedSpan] = []
+    open_marker: tuple[ManagedMarker, int] | None = None
+    fence: tuple[int, int] | None = None
+    unsupported = False
+    malformed = False
+    for start, end, content, ending in _iter_binary_lines(data):
+        if fence is not None:
+            if _fence_close(content, fence):
+                fence = None
+            continue
+        opener = _fence_open(content)
+        if opener is not None:
+            fence = opener
+            continue
+        marker = _MANAGED_BEGIN_MARKERS.get(content) if ending else None
+        end_markers = _MANAGED_END_MARKERS.get(content, ()) if ending else ()
+        if marker is not None:
+            if open_marker is not None:
+                malformed = True
+            else:
+                open_marker = (marker, start)
+            continue
+        if end_markers:
+            if open_marker is None:
+                malformed = True
+                continue
+            active, span_start = open_marker
+            if active.end != content:
+                malformed = True
+                open_marker = None
+                continue
+            spans.append(
+                ManagedSpan(
+                    kind=active.kind,
+                    version=active.version,
+                    variant=active.variant,
+                    start=span_start,
+                    end=end,
+                )
+            )
+            open_marker = None
+            continue
+        if _looks_like_contextguard_marker(content):
+            unsupported = True
+    if open_marker is not None:
+        malformed = True
+    if malformed:
+        return ManagedParseResult("malformed", tuple(spans), "malformed managed marker structure")
+    if unsupported:
+        return ManagedParseResult("unsupported", tuple(spans), "unsupported managed marker literal")
+    return ManagedParseResult("valid" if spans else "absent", tuple(spans))
+
+
+def parse_managed_bytes(data: bytes, *, kind: str | None = None) -> ManagedParseResult:
+    """Classify exact ContextGuard-managed raw-byte spans without decoding user bytes."""
+    scanned = _scan_managed_spans(data)
+    if scanned.status in {"malformed", "unsupported"}:
+        return scanned
+    spans = tuple(span for span in scanned.spans if kind is None or span.kind == kind)
+    by_kind: dict[str, int] = {}
+    for span in spans:
+        by_kind[span.kind] = by_kind.get(span.kind, 0) + 1
+    if any(count > 1 for count in by_kind.values()) or (kind is None and len(spans) > 1):
+        return ManagedParseResult("ambiguous", spans, "multiple managed spans")
+    return ManagedParseResult("valid" if spans else "absent", spans)
+
 
 class CapabilityClass:
     """How ContextGuard can integrate with a given agent."""
@@ -375,15 +633,14 @@ def render_repo_rule_block() -> str:
     ])
 
 
-def render_codex_skill() -> str:
-    """Render the optional project-local Codex skill for ContextGuard."""
+def _render_codex_skill_with_markers(begin: str, end: str) -> str:
     return "\n".join([
         "---",
         "name: context-guard",
         "description: Use ContextGuard helpers to keep Codex context focused with local-first setup, audit, trimming, and artifact commands.",
         "---",
         "",
-        CODEX_SKILL_MARKER_BEGIN,
+        begin,
         "# ContextGuard for Codex",
         "",
         "Use this skill when a task would otherwise paste large files, long logs, or repeated setup context into Codex.",
@@ -400,11 +657,38 @@ def render_codex_skill() -> str:
         "- If `context-guard` is not on PATH, install it explicitly or run via `npx @ictechgy/context-guard`.",
         "",
         "Do not claim fixed token or cost savings from these helpers; treat byte reductions as local proxy evidence only.",
-        CODEX_SKILL_MARKER_END,
+        end,
         "",
     ])
 
 
+def render_codex_skill() -> str:
+    """Render the v1 project-local Codex skill."""
+    return _render_codex_skill_with_markers(CODEX_SKILL_MARKER_BEGIN, CODEX_SKILL_MARKER_END)
+
+
+def render_legacy_codex_skill_v0() -> str:
+    """Render the exact legacy whole-file image released before managed-span v1."""
+    return _render_codex_skill_with_markers(
+        LEGACY_CODEX_SKILL_MARKER_BEGIN,
+        LEGACY_CODEX_SKILL_MARKER_END,
+    )
+
+
+LEGACY_CODEX_SKILL_SHA256_ALLOWLIST = {
+    hashlib.sha256(render_legacy_codex_skill_v0().encode("utf-8")).hexdigest(): "legacy-v0-current",
+}
+
+
+def render_codex_skill_block_bytes() -> bytes:
+    rendered = render_codex_skill().encode("utf-8")
+    start = rendered.index(CODEX_SKILL_MARKER_V1_BEGIN)
+    end = rendered.index(CODEX_SKILL_MARKER_V1_END, start) + len(CODEX_SKILL_MARKER_V1_END)
+    if rendered[end : end + 1] == b"\n":
+        end += 1
+    return rendered[start:end]
+
+
 def _brief_mode_source_candidates(level: str) -> list[Path]:
     """Return deterministic source candidates for packaged/repo brief snippets."""
     filename = f"brief-mode.{level}.md"
@@ -476,6 +760,39 @@ def render_brief_mode_block(level: str) -> str:
     return render_fallback_brief_mode_block(level)
 
 
+def render_quiet_narration_block() -> str:
+    """Render embedded canonical bytes without opening any non-target file."""
+    return "\n".join([
+        NARRATION_MODE_MARKER_BEGIN.decode("ascii"),
+        "## ContextGuard quiet narration (advisory)",
+        "",
+        "Best effort: reduce only discretionary intermediate narration. Skip routine preambles,",
+        "per-tool narration, filler, and repeated interim summaries when they add no useful",
+        "information.",
+        "",
+        "Always preserve required user-facing communication:",
+        "",
+        "- user approvals and decisions;",
+        "- blockers and failures;",
+        "- destructive-risk and security warnings;",
+        "- progress required by higher-priority instructions;",
+        "- the final result;",
+        "- changed files; and",
+        "- verification evidence.",
+        "",
+        "This mode does not require a shorter final answer and does not change reasoning effort.",
+        "It asks Claude to reduce discretionary narration; it does not guarantee token or cost savings,",
+        "and no numeric savings should be claimed without matched provider evidence.",
+        NARRATION_MODE_MARKER_END.decode("ascii"),
+    ])
+
+
+def _append_narration_block_bytes(existing: bytes, block: bytes) -> bytes:
+    """Append one deterministic separator that default-mode removes with the span."""
+    block = block.rstrip(b"\r\n") + b"\n"
+    return block if not existing else existing + b"\n" + block
+
+
 def _brief_mode_levels_in_text(text: str) -> list[str]:
     return [match.group("level") for match in BRIEF_MODE_BLOCK_RE.finditer(text)]
 
@@ -494,37 +811,107 @@ def _append_managed_block(existing: str, block: str) -> str:
     return block + "\n"
 
 
-def compose_rule_file_text(
-    existing: str | None,
+def _managed_block_bytes(block: str) -> bytes:
+    return block.encode("utf-8").rstrip(b"\r\n") + b"\n"
+
+
+def _append_managed_block_bytes(existing: bytes, block: bytes) -> bytes:
+    block = block.rstrip(b"\r\n") + b"\n"
+    if not existing:
+        return block
+    if existing.endswith(b"\n\n"):
+        separator = b""
+    elif existing.endswith(b"\n"):
+        separator = b"\n"
+    else:
+        separator = b"\n\n"
+    return existing + separator + block
+
+
+def _managed_span_for_kind(data: bytes, kind: str) -> ManagedSpan | None:
+    parsed = parse_managed_bytes(data, kind=kind)
+    if parsed.status == "absent":
+        return None
+    if parsed.status != "valid":
+        raise ValueError(parsed.reason or f"{parsed.status} managed {kind} markers")
+    return parsed.spans[0]
+
+
+def _replace_managed_span(data: bytes, span: ManagedSpan, block: bytes) -> bytes:
+    return data[: span.start] + block.rstrip(b"\r\n") + b"\n" + data[span.end :]
+
+
+def _brief_mode_levels_in_bytes(data: bytes) -> list[str]:
+    parsed = _scan_managed_spans(data)
+    return [
+        str(span.variant)
+        for span in parsed.spans
+        if span.kind == "brief-mode" and span.variant in BRIEF_MODE_LEVELS
+    ]
+
+
+def compose_rule_file_bytes(
+    existing: bytes | None,
     *,
     with_init: bool,
     brief_mode: str | None,
-) -> tuple[str, dict[str, Any]]:
-    """Compose final repo rule text for combined init and brief-mode mutations."""
-    text = existing or ""
-    original_text = text
-    existing_brief_levels = _brief_mode_levels_in_text(text)
+) -> tuple[bytes, dict[str, Any]]:
+    """Compose rule-file mutations from exact owned spans, preserving all other bytes."""
+    data = existing or b""
+    original = data
+    before_brief = _brief_mode_levels_in_bytes(data)
     meta: dict[str, Any] = {
         "init_changed": False,
-        "init_present_before": ADAPTER_RULE_BLOCK_BEGIN in text,
-        "brief_levels_before": existing_brief_levels,
+        "init_present_before": False,
+        "init_migrated_legacy": False,
+        "brief_levels_before": before_brief,
         "brief_changed": False,
     }
-    if with_init and ADAPTER_RULE_BLOCK_BEGIN not in text:
-        text = _append_managed_block(text, render_repo_rule_block())
-        meta["init_changed"] = True
+    repo_span = _managed_span_for_kind(data, "repo-rules")
+    meta["init_present_before"] = repo_span is not None
+    if with_init:
+        block = _managed_block_bytes(render_repo_rule_block())
+        if repo_span is None:
+            data = _append_managed_block_bytes(data, block)
+            meta["init_changed"] = True
+        elif data[repo_span.start : repo_span.end] != block:
+            data = _replace_managed_span(data, repo_span, block)
+            meta["init_changed"] = True
+            meta["init_migrated_legacy"] = repo_span.version == 0
+
     if brief_mode:
-        stripped, removed_levels = _remove_brief_mode_blocks(text)
+        span = _managed_span_for_kind(data, "brief-mode")
+        removed = [str(span.variant)] if span is not None and span.variant else []
+        meta["brief_levels_removed"] = removed
         if brief_mode == BRIEF_MODE_OFF:
-            text = stripped
-            meta["brief_changed"] = bool(removed_levels)
+            if span is not None:
+                data = data[: span.start] + data[span.end :]
+                meta["brief_changed"] = True
         else:
-            block = render_brief_mode_block(brief_mode)
-            text = _append_managed_block(stripped, block)
-            meta["brief_changed"] = removed_levels != [brief_mode] or text != original_text
-        meta["brief_levels_removed"] = removed_levels
-    meta["changed"] = text != original_text
-    return text, meta
+            block = _managed_block_bytes(render_brief_mode_block(brief_mode))
+            if span is None:
+                data = _append_managed_block_bytes(data, block)
+                meta["brief_changed"] = True
+            elif data[span.start : span.end] != block:
+                data = _replace_managed_span(data, span, block)
+                meta["brief_changed"] = True
+    meta["changed"] = data != original
+    return data, meta
+
+
+def compose_rule_file_text(
+    existing: str | None,
+    *,
+    with_init: bool,
+    brief_mode: str | None,
+) -> tuple[str, dict[str, Any]]:
+    """Compatibility text wrapper around the byte-exact managed composer."""
+    rendered, meta = compose_rule_file_bytes(
+        existing.encode("utf-8") if existing is not None else None,
+        with_init=with_init,
+        brief_mode=brief_mode,
+    )
+    return rendered.decode("utf-8"), meta
 
 
 def plan_or_write_rule_file_blocks(
@@ -534,7 +921,7 @@ def plan_or_write_rule_file_blocks(
     brief_mode: str | None,
     applied: bool,
 ) -> dict[str, Any]:
-    """Plan or apply managed rule-file blocks with one original backup per changed existing write."""
+    """Plan/apply exact managed spans through the shared cooperative writer."""
     result: dict[str, Any] = {
         "status": None,
         "planned_actions": [],
@@ -551,27 +938,38 @@ def plan_or_write_rule_file_blocks(
         result["planned_actions"].append(reason)
         return result
 
-    existing = state.get("text")
-    existing_text = str(existing or "")
-    result["brief_mode_existing_levels"] = _brief_mode_levels_in_text(existing_text)
-    rule_present = existing is not None and ADAPTER_RULE_BLOCK_BEGIN in existing_text
-    planned_meta: dict[str, Any] | None = None
-    if brief_mode:
-        _, planned_meta = compose_rule_file_text(existing, with_init=with_init, brief_mode=brief_mode)
+    existing = state.get("bytes")
+    snapshot = state["snapshot"]
+    existing_bytes = bytes(existing or b"")
+    result["brief_mode_existing_levels"] = _brief_mode_levels_in_bytes(existing_bytes)
+    repo_state = parse_managed_bytes(existing_bytes, kind="repo-rules")
+    rule_present = repo_state.status == "valid"
+    try:
+        final_bytes, planned_meta = compose_rule_file_bytes(
+            existing,
+            with_init=with_init,
+            brief_mode=brief_mode,
+        )
+    except ValueError as exc:
+        reason = f"refused unsafe managed rule state in {path.name}: {exc}"
+        result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
+        result["planned_actions"].append(reason)
+        return result
 
     if with_init:
-        if rule_present:
+        if rule_present and not planned_meta["init_changed"]:
             result["status"] = "exists"
             result["planned_actions"].append("advisory ContextGuard rules already present")
         elif not applied:
             result["status"] = "planned"
-            result["planned_actions"].append("would add advisory ContextGuard rules")
+            verb = "migrate" if planned_meta.get("init_migrated_legacy") else "add"
+            result["planned_actions"].append(f"would {verb} advisory ContextGuard rules")
     elif not brief_mode:
         result["status"] = "planned"
         result["planned_actions"].append("run with --with-init to add advisory ContextGuard rules")
 
     if brief_mode:
-        brief_changed = bool(planned_meta and planned_meta.get("brief_changed"))
+        brief_changed = bool(planned_meta.get("brief_changed"))
         if brief_mode == BRIEF_MODE_OFF:
             if brief_changed:
                 result["brief_mode_status"] = "planned" if not applied else None
@@ -595,7 +993,7 @@ def plan_or_write_rule_file_blocks(
             result["status"] = "planned" if result["planned_actions"] else "unchanged"
         return result
 
-    final_text, meta = compose_rule_file_text(existing, with_init=with_init, brief_mode=brief_mode)
+    meta = planned_meta
     if not meta["changed"]:
         if result["status"] is None:
             result["status"] = "exists" if rule_present else "unchanged"
@@ -603,33 +1001,29 @@ def plan_or_write_rule_file_blocks(
             result["brief_mode_status"] = "absent" if brief_mode == BRIEF_MODE_OFF else "exists"
         return result
 
-    backup_path = None
-    if existing is not None:
-        try:
-            backup_path = backup_existing(path)
-        except OSError as exc:
-            reason = f"could not back up repo rule file {path.name}: {exc.__class__.__name__}"
-            result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
-            result["planned_actions"] = [reason]
-            return result
-    durability_warning = None
-    try:
-        atomic_write(
-            path,
-            final_text,
-            existing_mode_or_default(path, 0o644) if existing is not None else 0o644,
-            dir_mode=0o755,
-        )
-    except AtomicWriteDurabilityError as exc:
-        durability_warning = str(exc)
-    except OSError as exc:
-        reason = f"could not write repo rule file {path.name}: {exc.__class__.__name__}"
-        result.update({"status": "skipped", "brief_mode_status": "skipped", "reason": reason})
+    write_result = write_managed_file(
+        path,
+        expected=snapshot,
+        desired=final_bytes,
+        mode=0o644,
+        dir_mode=0o755,
+    )
+    if write_result["status"] not in {"applied", "applied-durability-uncertain"}:
+        reason = write_result.get("reason") or f"could not write repo rule file {path.name}"
+        result.update({
+            "status": write_result["status"],
+            "brief_mode_status": write_result["status"],
+            "reason": reason,
+        })
         result["planned_actions"] = [reason]
         return result
-
-    if backup_path:
-        result["brief_mode_backup_path"] = str(backup_path)
+    if write_result.get("backup_path"):
+        result["brief_mode_backup_path"] = write_result["backup_path"]
+    durability_warning = (
+        write_result.get("reason")
+        if write_result["status"] == "applied-durability-uncertain"
+        else None
+    )
     if durability_warning:
         result["status"] = "applied-durability-uncertain"
         result["reason"] = durability_warning
@@ -641,7 +1035,7 @@ def plan_or_write_rule_file_blocks(
         else:
             result["planned_actions"].append("advisory ContextGuard rules already present")
     elif result["status"] is None:
-        result["status"] = "unchanged"
+        result["status"] = "applied"
     if brief_mode:
         if brief_mode == BRIEF_MODE_OFF:
             result["brief_mode_status"] = "removed" if meta["brief_changed"] else "absent"
@@ -686,6 +1080,7 @@ def _existing_rule_parent_issue(path: Path) -> str | None:
     because plan/apply must agree and must never follow an attacker-swapped rule
     directory outside the project.
     """
+    path = _normalize_allowed_first_absolute_symlink(path)
     parts = path.parts[1:-1] if path.is_absolute() else path.parts[:-1]
     if not parts:
         return None
@@ -706,14 +1101,20 @@ def _existing_rule_parent_issue(path: Path) -> str | None:
 
 
 def _rule_file_state(path: Path) -> dict[str, Any]:
-    """Return a non-throwing state for project rule/skill files."""
+    """Return a non-throwing exact-byte snapshot for project rule/skill files."""
     parent_issue = _existing_rule_parent_issue(path)
     if parent_issue:
         return {"status": "unsafe", "text": None, "reason": parent_issue}
     try:
         st = os.lstat(path)
     except FileNotFoundError:
-        return {"status": "missing", "text": None, "reason": None}
+        return {
+            "status": "missing",
+            "text": None,
+            "bytes": None,
+            "snapshot": ManagedFileSnapshot(None, None),
+            "reason": None,
+        }
     except OSError as exc:
         return {"status": "unsafe", "text": None, "reason": f"could not inspect rule file: {exc.__class__.__name__}"}
     if stat.S_ISLNK(st.st_mode):
@@ -721,20 +1122,35 @@ def _rule_file_state(path: Path) -> dict[str, Any]:
     if stat.S_ISDIR(st.st_mode):
         return {"status": "directory", "text": None, "reason": f"refused to replace directory rule target: {path.name}"}
     try:
-        text = _read_text_no_follow(path)
+        snapshot = read_managed_file_snapshot(path)
     except OSError as exc:
         return {
             "status": "unsafe",
             "text": None,
+            "bytes": None,
             "reason": f"could not read rule file without following symlinks: {exc.__class__.__name__}",
         }
-    return {"status": "file", "text": text, "reason": None}
+    data = snapshot.data or b""
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError:
+        text = None
+    return {
+        "status": "file",
+        "text": text,
+        "bytes": data,
+        "snapshot": snapshot,
+        "reason": None,
+    }
 
 
 def repo_rule_block_present(path: Path) -> bool:
     """True when the advisory ContextGuard block already exists in the rule file."""
     state = _rule_file_state(path)
-    return state["status"] == "file" and ADAPTER_RULE_BLOCK_BEGIN in str(state.get("text") or "")
+    return (
+        state["status"] == "file"
+        and parse_managed_bytes(bytes(state.get("bytes") or b""), kind="repo-rules").status == "valid"
+    )
 
 
 def write_repo_rule_init(path: Path) -> dict[str, Any]:
@@ -747,36 +1163,24 @@ def write_repo_rule_init(path: Path) -> dict[str, Any]:
     state = _rule_file_state(path)
     if state["status"] not in {"missing", "file"}:
         return {"status": "skipped", "reason": state.get("reason") or f"refused unsafe rule target: {path.name}"}
-    existing = state.get("text")
-    if existing is not None and ADAPTER_RULE_BLOCK_BEGIN in existing:
-        return {"status": "exists"}
-    block = render_repo_rule_block()
-    if existing:
-        new_text = existing.rstrip("\n") + "\n\n" + block + "\n"
-    else:
-        new_text = block + "\n"
-    mode = existing_mode_or_default(path, 0o644) if existing is not None else 0o644
-    backup_path = None
-    if existing is not None:
-        try:
-            backup_path = backup_existing(path)
-        except OSError as exc:
-            return {"status": "skipped", "reason": f"could not back up repo rule file {path.name}: {exc.__class__.__name__}"}
-    durability_warning = None
     try:
-        atomic_write(path, new_text, mode, dir_mode=0o755)
-    except AtomicWriteDurabilityError as exc:
-        durability_warning = str(exc)
-    except OSError as exc:
-        result = {"status": "skipped", "reason": f"could not write repo rule file {path.name}: {exc.__class__.__name__}"}
-        if backup_path:
-            result["backup_path"] = str(backup_path)
-        return result
-    result = {"status": "applied", "backup_path": str(backup_path) if backup_path else None}
-    if durability_warning:
-        result["status"] = "applied-durability-uncertain"
-        result["reason"] = durability_warning
-    return result
+        final, meta = compose_rule_file_bytes(
+            state.get("bytes"),
+            with_init=True,
+            brief_mode=None,
+        )
+    except ValueError as exc:
+        return {"status": "skipped", "reason": f"refused unsafe managed rule state: {exc}"}
+    if not meta["changed"]:
+        return {"status": "exists"}
+    write_result = write_managed_file(
+        path,
+        expected=state["snapshot"],
+        desired=final,
+        mode=0o644,
+        dir_mode=0o755,
+    )
+    return write_result
 
 
 def codex_skill_status(path: Path) -> str:
@@ -785,10 +1189,17 @@ def codex_skill_status(path: Path) -> str:
         return "missing"
     if state["status"] != "file":
         return "unsafe"
-    text = str(state.get("text") or "")
-    if text == render_codex_skill():
+    data = bytes(state.get("bytes") or b"")
+    if data == render_codex_skill().encode("utf-8"):
         return "exists"
-    if CODEX_SKILL_MARKER_BEGIN in text and CODEX_SKILL_MARKER_END in text:
+    parsed = parse_managed_bytes(data, kind="codex-skill")
+    if parsed.status != "valid":
+        return "foreign"
+    span = parsed.spans[0]
+    if span.version == 0:
+        digest = hashlib.sha256(data).hexdigest()
+        return "update-needed" if digest in LEGACY_CODEX_SKILL_SHA256_ALLOWLIST else "foreign"
+    if span.version == 1:
         return "update-needed"
     return "foreign"
 
@@ -806,11 +1217,29 @@ def write_codex_project_skill(path: Path) -> dict[str, Any]:
             "status": "skipped",
             "reason": f"refused to overwrite non-ContextGuard Codex skill file: {path}",
         }
-    try:
-        atomic_write(path, render_codex_skill(), 0o644, dir_mode=0o755)
-    except OSError as exc:
-        return {"status": "skipped", "reason": f"could not write Codex skill file {path}: {exc.__class__.__name__}"}
-    return {"status": "updated" if status == "update-needed" else "applied"}
+    existing = state.get("bytes")
+    if status == "missing":
+        desired = render_codex_skill().encode("utf-8")
+    else:
+        data = bytes(existing or b"")
+        parsed = parse_managed_bytes(data, kind="codex-skill")
+        span = parsed.spans[0]
+        if span.version == 0:
+            desired = render_codex_skill().encode("utf-8")
+        else:
+            desired = _replace_managed_span(data, span, render_codex_skill_block_bytes())
+    result = write_managed_file(
+        path,
+        expected=state["snapshot"],
+        desired=desired,
+        mode=0o644,
+        dir_mode=0o755,
+    )
+    if result["status"] == "applied":
+        result["status"] = "updated" if status == "update-needed" else "applied"
+    elif result["status"] == "applied-durability-uncertain":
+        result["change_kind"] = "updated" if status == "update-needed" else "applied"
+    return result
 
 
 def adapter_rule_path(root: Path, adapter: AgentAdapter) -> Path | None:
@@ -1005,14 +1434,23 @@ def build_adapter_plan(
                     entry["planned_actions"].append(
                         f"would generate project Codex skill at {adapter.project_skill_rel}"
                     )
+                elif entry["status"] == "applied-durability-uncertain":
+                    entry["project_skill_status"] = "blocked-durability-uncertain"
+                    entry["planned_actions"].append(
+                        "blocked project Codex skill write because the preceding rule-file "
+                        "commit has uncertain directory durability"
+                    )
                 else:
                     skill_result = write_codex_project_skill(skill_path)
                     entry["project_skill_status"] = skill_result["status"]
-                    if skill_result["status"] in {"applied", "updated"}:
+                    if skill_result["status"] in {"applied", "updated", "applied-durability-uncertain"}:
                         action = f"wrote project Codex skill to {adapter.project_skill_rel}"
                         entry["applied_actions"].append(action)
                         entry["planned_actions"].append(action)
-                        if entry["status"] in {"planned", "exists", "unchanged"}:
+                        if skill_result["status"] == "applied-durability-uncertain":
+                            entry["status"] = "applied-durability-uncertain"
+                            entry["reason"] = skill_result.get("reason")
+                        elif entry["status"] in {"planned", "exists", "unchanged"}:
                             entry["status"] = "applied"
                     elif skill_result["status"] == "exists":
                         entry["planned_actions"].append(
@@ -1272,10 +1710,10 @@ def _ensure_directory_no_symlink(path: Path, mode: int | None = None, *, parents
         raise
 
 
-def _read_text_no_follow(path: Path) -> str:
+def _read_bytes_no_follow(path: Path) -> bytes:
     fd = _open_regular_no_symlink(path)
     try:
-        with os.fdopen(fd, "r", encoding="utf-8") as handle:
+        with os.fdopen(fd, "rb") as handle:
             fd = -1
             return handle.read()
     finally:
@@ -1283,6 +1721,47 @@ def _read_text_no_follow(path: Path) -> str:
             os.close(fd)
 
 
+def _read_text_no_follow(path: Path) -> str:
+    return _read_bytes_no_follow(path).decode("utf-8")
+
+
+def _snapshot_metadata(st: os.stat_result) -> tuple[int, int, int, int, int]:
+    return (
+        int(st.st_dev),
+        int(st.st_ino),
+        int(st.st_mode),
+        int(st.st_size),
+        int(st.st_mtime_ns),
+    )
+
+
+def read_managed_file_snapshot(path: Path) -> ManagedFileSnapshot:
+    """Read an exact byte+metadata snapshot without following target/parent links."""
+    try:
+        fd = _open_regular_no_symlink(path)
+    except FileNotFoundError:
+        return ManagedFileSnapshot(None, None)
+    try:
+        before = os.fstat(fd)
+        with os.fdopen(fd, "rb") as handle:
+            fd = -1
+            data = handle.read()
+            after = os.fstat(handle.fileno())
+        if _snapshot_metadata(before) != _snapshot_metadata(after) or len(data) != after.st_size:
+            raise ManagedFileConflictError(f"managed target changed during read: {path}")
+        return ManagedFileSnapshot(data, _snapshot_metadata(after))
+    finally:
+        if fd != -1:
+            os.close(fd)
+
+
+def _verify_expected_snapshot(path: Path, expected: ManagedFileSnapshot) -> ManagedFileSnapshot:
+    current = read_managed_file_snapshot(path)
+    if current != expected:
+        raise ManagedFileConflictError(f"managed target changed since planning: {path}")
+    return current
+
+
 def _read_optional_text_no_follow(path: Path) -> str | None:
     try:
         return _read_text_no_follow(path)
@@ -1318,7 +1797,12 @@ def load_json_object(path: Path) -> dict[str, Any]:
     return _parse_json_object_text(_read_optional_text_no_follow(path), path)
 
 
-def ensure_permissions(settings: dict[str, Any], actions: list[str]) -> None:
+def ensure_permissions(
+    settings: dict[str, Any],
+    actions: list[str],
+    *,
+    migrate_env_read_denies: bool = False,
+) -> None:
     permissions = settings.get("permissions")
     if permissions is None:
         permissions = {}
@@ -1331,6 +1815,21 @@ def ensure_permissions(settings: dict[str, Any], actions: list[str]) -> None:
         permissions["deny"] = deny
     if not isinstance(deny, list):
         raise SystemExit("Refusing to replace non-list settings.permissions.deny; repair it manually first.")
+    if migrate_env_read_denies:
+        retained = [
+            rule
+            for rule in deny
+            if not (
+                isinstance(rule, str)
+                and rule in PRODUCT_OWNED_ENV_READ_DENIES
+            )
+        ]
+        removed = len(deny) - len(retained)
+        if removed:
+            deny[:] = retained
+            actions.append(
+                f"removed {removed} obsolete permissions.deny rules now enforced by the Claude Read hook"
+            )
     added = 0
     for rule in RECOMMENDED_DENIES:
         if rule not in deny:
@@ -1378,9 +1877,11 @@ def _path_has_symlink_component(path: Path) -> bool:
 
 
 def _probe_path_helper_identity(path: Path, helper_name: str) -> None:
-    env = os.environ.copy()
     system_path = os.pathsep.join(part for part in ("/usr/bin", "/bin", "/usr/sbin", "/sbin") if Path(part).is_dir())
-    env["PATH"] = str(path.parent) + (os.pathsep + system_path if system_path else "")
+    env = {
+        "LC_ALL": "C",
+        "PATH": str(path.parent) + (os.pathsep + system_path if system_path else ""),
+    }
     try:
         proc = subprocess.Popen(
             [str(path), "--help"],
@@ -1517,89 +2018,765 @@ def helper_command(helper_name: str, kit_script: str, *, shell: str | None = Non
     return shlex.join(argv)
 
 
-def statusline_setting(*, allow_path_fallback: bool = False) -> dict[str, str]:
-    return {"type": "command", "command": helper_command(HELPER_STATUSLINE, "statusline_merged.sh", shell="bash", allow_path_fallback=allow_path_fallback)}
-
-
-def bash_hook_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
-    return {
-        "matcher": "Bash",
-        "hooks": [{"type": "command", "command": helper_command(HELPER_REWRITE_BASH, "rewrite_bash_for_token_budget.py", allow_path_fallback=allow_path_fallback)}],
-    }
+def _validated_runtime_executable(raw: str | Path, *, label: str) -> Path:
+    """Bind a runtime/helper to the canonical executable seen during setup."""
+    candidate = Path(raw)
+    if not candidate.is_absolute():
+        raise SystemExit(f"{label} did not resolve to an absolute path")
+    try:
+        canonical = candidate.resolve(strict=True)
+        metadata = canonical.stat()
+    except OSError as exc:
+        raise SystemExit(
+            f"{label} could not be canonicalized: {exc.strerror or exc.__class__.__name__}"
+        ) from exc
+    if not stat.S_ISREG(metadata.st_mode) or not os.access(canonical, os.X_OK):
+        raise SystemExit(f"{label} must be an executable regular file")
+    return canonical
 
 
-def read_hook_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
-    return {
-        "matcher": "Read",
-        "hooks": [{"type": "command", "command": helper_command(HELPER_GUARD_READ, "guard_large_read.py", allow_path_fallback=allow_path_fallback)}],
-    }
+def _approved_python_runtime() -> Path:
+    if not sys.executable:
+        raise SystemExit("Python runtime identity is unavailable")
+    return _validated_runtime_executable(sys.executable, label="Python runtime")
 
 
-def failed_nudge_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
-    return {
-        "matcher": "Bash",
-        "hooks": [{"type": "command", "command": helper_command(HELPER_FAILED_NUDGE, "failed_attempt_nudge.py", allow_path_fallback=allow_path_fallback)}],
-    }
+def _approved_system_runtime(name: str) -> Path:
+    found = shutil.which(name, path=ISOLATED_RUNTIME_PATH)
+    if not found:
+        raise SystemExit(f"Required {name!r} runtime was not found in the fixed system path")
+    return _validated_runtime_executable(found, label=f"{name} runtime")
 
 
-def command_matches(existing: str, desired: str) -> bool:
-    if existing == desired:
-        return True
-    try:
-        existing_parts = shlex.split(existing) if existing else []
-        desired_parts = shlex.split(desired) if desired else []
-    except ValueError:
-        return False
-    return bool(existing_parts and desired_parts and existing_parts == desired_parts)
+def _isolated_runtime_prefix(
+    preserve_env_names: tuple[str, ...] = (),
+    *,
+    fixed_env: dict[str, str] | None = None,
+) -> list[str]:
+    prefix = [
+        str(_approved_system_runtime("env")),
+        "-i",
+        f"PATH={ISOLATED_RUNTIME_PATH}",
+        "LC_ALL=C",
+    ]
+    for name in preserve_env_names:
+        value = os.environ.get(name)
+        if value is not None and BEHAVIOR_ENV_VALUE_RE.fullmatch(value):
+            prefix.append(f"{name}={value}")
+    for name, value in (fixed_env or {}).items():
+        if name in {"HOME"} and value and "\x00" not in value:
+            prefix.append(f"{name}={value}")
+    return prefix
 
 
-def command_helper_basenames(command: str) -> set[str]:
-    try:
-        parts = shlex.split(command) if command else []
-    except ValueError:
-        return set()
-    if not parts:
-        return set()
-    index = 0
-    if os.path.basename(parts[index]) == "env":
-        index += 1
-        while index < len(parts) and "=" in parts[index] and not parts[index].startswith("-"):
-            index += 1
-    if index >= len(parts):
-        return set()
-    head = os.path.basename(parts[index])
-    interpreter_heads = {"bash", "sh"}
-    if re.fullmatch(r"python(?:\d+(?:\.\d+)?)?", head):
-        interpreter_heads.add(head)
-    if head in interpreter_heads:
-        for token_index in range(index + 1, len(parts)):
-            token = parts[token_index]
-            if token == "-c":
-                if token_index + 1 < len(parts):
-                    return command_helper_basenames(parts[token_index + 1])
-                return set()
-            if token.startswith("-"):
-                continue
-            return {os.path.basename(token)}
-        return set()
-    return {head}
+def _helper_path_from_argv(argv: list[str], *, label: str) -> Path:
+    if not argv:
+        raise SystemExit(f"{label} helper argv is empty")
+    return _validated_runtime_executable(argv[-1], label=label)
 
 
-def equivalent_helper_basenames(command: str) -> set[str]:
-    bases = command_helper_basenames(command)
-    equivalents = set(bases)
-    for base in bases:
-        equivalents.update(HELPER_EQUIVALENT_BASENAMES.get(base, ()))
-    return equivalents
+def _bundled_helper_candidates(helper_name: str, kit_script: str) -> set[Path]:
+    script_dir = Path(__file__).resolve().parent
+    raw_candidates = (
+        script_dir / helper_name,
+        script_dir.parent / "plugins" / "context-guard" / "bin" / helper_name,
+        script_dir / kit_script,
+    )
+    candidates: set[Path] = set()
+    for candidate in raw_candidates:
+        try:
+            candidates.add(candidate.resolve(strict=True))
+        except OSError:
+            continue
+    return candidates
 
 
-def command_matches_existing_or_equivalent(existing: str, desired: str) -> bool:
+def automatic_helper_argv(
+    helper_name: str,
+    kit_script: str,
+    *,
+    shell: str | None = None,
+    allow_path_fallback: bool = False,
+    preserve_env_names: tuple[str, ...] = (),
+    fixed_env: dict[str, str] | None = None,
+) -> list[str]:
+    """Build installed hook argv with isolated, setup-pinned runtimes."""
+    resolved = helper_argv(
+        helper_name,
+        kit_script,
+        shell=shell,
+        allow_path_fallback=allow_path_fallback,
+    )
+    helper_path = _helper_path_from_argv(resolved, label=helper_name)
+    prefix = _isolated_runtime_prefix(
+        preserve_env_names,
+        fixed_env=fixed_env,
+    )
+    if helper_path not in _bundled_helper_candidates(helper_name, kit_script):
+        # An explicit PATH fallback may be a native executable. Its absolute
+        # identity was already validated by validate_path_helper_fallback().
+        return [*prefix, str(helper_path)]
+    if shell:
+        shell_runtime = _approved_system_runtime(shell)
+        shell_flags = ["--noprofile", "--norc"] if shell_runtime.name == "bash" else []
+        return [*prefix, str(shell_runtime), *shell_flags, str(helper_path)]
+    return [*prefix, str(_approved_python_runtime()), "-I", str(helper_path)]
+
+
+def automatic_helper_command(
+    helper_name: str,
+    kit_script: str,
+    *,
+    shell: str | None = None,
+    allow_path_fallback: bool = False,
+    preserve_env_names: tuple[str, ...] = (),
+    fixed_env: dict[str, str] | None = None,
+) -> str:
+    return shlex.join(
+        automatic_helper_argv(
+            helper_name,
+            kit_script,
+            shell=shell,
+            allow_path_fallback=allow_path_fallback,
+            preserve_env_names=preserve_env_names,
+            fixed_env=fixed_env,
+        )
+    )
+
+
+def _secure_owned_regular_path(path: Path, *, executable: bool) -> Path | None:
+    """Validate an approval path and every parent without following symlinks."""
+    try:
+        canonical = path.resolve(strict=True)
+    except OSError:
+        return None
+    if not path.is_absolute() or canonical != path:
+        return None
+    allowed_owners = {0, os.geteuid()}
+    current = Path(path.anchor)
+    components = path.parts[1:]
+    if not components:
+        return None
+    try:
+        root_metadata = os.lstat(current)
+        if (
+            stat.S_ISLNK(root_metadata.st_mode)
+            or not stat.S_ISDIR(root_metadata.st_mode)
+            or root_metadata.st_uid not in allowed_owners
+            or stat.S_IMODE(root_metadata.st_mode) & 0o022
+        ):
+            return None
+        for index, component in enumerate(components):
+            current = current / component
+            metadata = os.lstat(current)
+            is_leaf = index == len(components) - 1
+            if stat.S_ISLNK(metadata.st_mode):
+                return None
+            if metadata.st_uid not in allowed_owners or stat.S_IMODE(metadata.st_mode) & 0o022:
+                return None
+            if is_leaf:
+                if not stat.S_ISREG(metadata.st_mode):
+                    return None
+                if executable and not os.access(current, os.X_OK):
+                    return None
+            elif not stat.S_ISDIR(metadata.st_mode):
+                return None
+    except OSError:
+        return None
+    return canonical
+
+
+def _secure_owned_directory_path(path: Path) -> Path | None:
+    try:
+        canonical = path.resolve(strict=True)
+    except OSError:
+        return None
+    if not path.is_absolute() or canonical != path:
+        return None
+    allowed_owners = {0, os.geteuid()}
+    current = Path(path.anchor)
+    try:
+        root_metadata = os.lstat(current)
+        if (
+            stat.S_ISLNK(root_metadata.st_mode)
+            or not stat.S_ISDIR(root_metadata.st_mode)
+            or root_metadata.st_uid not in allowed_owners
+            or stat.S_IMODE(root_metadata.st_mode) & 0o022
+        ):
+            return None
+        for component in path.parts[1:]:
+            current = current / component
+            metadata = os.lstat(current)
+            if (
+                stat.S_ISLNK(metadata.st_mode)
+                or not stat.S_ISDIR(metadata.st_mode)
+                or metadata.st_uid not in allowed_owners
+                or stat.S_IMODE(metadata.st_mode) & 0o022
+            ):
+                return None
+    except OSError:
+        return None
+    return canonical
+
+
+def _approved_node_runtime() -> Path | None:
+    system_node = shutil.which("node", path=ISOLATED_RUNTIME_PATH)
+    if system_node:
+        approved = _secure_owned_regular_path(Path(system_node), executable=True)
+        if approved is not None:
+            return approved
+
+    allowed_owners = {0, os.geteuid()}
+    for candidate in HOMEBREW_NODE_CANDIDATES:
+        if len(candidate.parents) < 2:
+            continue
+        allowed_root = candidate.parents[1]
+        if _secure_owned_directory_path(allowed_root) is None:
+            continue
+        if _secure_owned_directory_path(candidate.parent) is None:
+            continue
+        try:
+            link_metadata = os.lstat(candidate)
+            physical_target = candidate.resolve(strict=True)
+            physical_target.relative_to(allowed_root)
+        except (OSError, ValueError):
+            continue
+        if link_metadata.st_uid not in allowed_owners:
+            continue
+        approved = _secure_owned_regular_path(physical_target, executable=True)
+        if approved is not None:
+            return approved
+    return None
+
+
+def _approved_default_omc_hud() -> tuple[Path, Path] | None:
+    """Approve only the effective user's default OMC HUD and fixed-path Node."""
+    try:
+        passwd_home = Path(pwd.getpwuid(os.geteuid()).pw_dir)
+        canonical_home = passwd_home.resolve(strict=True)
+    except (KeyError, OSError, RuntimeError):
+        return None
+    if not passwd_home.is_absolute() or canonical_home != passwd_home:
+        return None
+    omc_script = _secure_owned_regular_path(
+        canonical_home / ".claude" / "hud" / "omc-hud.mjs",
+        executable=False,
+    )
+    if omc_script is None:
+        return None
+    node_runtime = _approved_node_runtime()
+    if node_runtime is None:
+        return None
+    return node_runtime, omc_script
+
+
+def _statusline_setting(*, allow_path_fallback: bool = False) -> tuple[dict[str, str], bool]:
+    approved_omc = _approved_default_omc_hud()
+    fixed_env = (
+        {"HOME": str(approved_omc[1].parents[2])}
+        if approved_omc is not None
+        else None
+    )
+    argv = automatic_helper_argv(
+        HELPER_STATUSLINE,
+        "statusline_merged.sh",
+        shell="bash",
+        allow_path_fallback=allow_path_fallback,
+        preserve_env_names=STATUSLINE_BEHAVIOR_ENV,
+        fixed_env=fixed_env,
+    )
+    token_path = _helper_path_from_argv(
+        helper_argv(
+            HELPER_STATUSLINE_PLAIN,
+            "statusline.sh",
+            shell="bash",
+            allow_path_fallback=allow_path_fallback,
+        ),
+        label=HELPER_STATUSLINE_PLAIN,
+    )
+    argv.extend(
+        [
+            "--approved-bash",
+            str(_approved_system_runtime("bash")),
+            "--approved-python",
+            str(_approved_python_runtime()),
+            "--approved-token-statusline",
+            str(token_path),
+        ]
+    )
+    if approved_omc is not None:
+        node_runtime, omc_script = approved_omc
+        argv.extend(
+            [
+                "--approved-node",
+                str(node_runtime),
+                "--approved-omc-script",
+                str(omc_script),
+            ]
+        )
+    return {"type": "command", "command": shlex.join(argv)}, approved_omc is not None
+
+
+def statusline_setting(*, allow_path_fallback: bool = False) -> dict[str, str]:
+    setting, _omc_included = _statusline_setting(allow_path_fallback=allow_path_fallback)
+    return setting
+
+
+def bash_hook_setting(*, allow_path_fallback: bool = False, bash_reference_v1: bool = False) -> dict[str, Any]:
+    command = automatic_helper_command(
+        HELPER_REWRITE_BASH,
+        "rewrite_bash_for_token_budget.py",
+        allow_path_fallback=allow_path_fallback,
+        preserve_env_names=REWRITE_BEHAVIOR_ENV,
+    )
+    if bash_reference_v1:
+        command = f"{command} --bash-reference-v1"
+    return {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": command}],
+    }
+
+
+def load_bash_reference_policy() -> object | None:
+    """Load only the package-local runtime policy, never an import from PATH."""
+    path = Path(__file__).resolve().parent / "bash_reference_policy.py"
+    flags = (
+        os.O_RDONLY
+        | getattr(os, "O_CLOEXEC", 0)
+        | getattr(os, "O_NONBLOCK", 0)
+        | getattr(os, "O_NOCTTY", 0)
+    )
+    if not hasattr(os, "O_NOFOLLOW"):
+        return None
+    flags |= os.O_NOFOLLOW
+    fd = -1
+    try:
+        fd = os.open(path, flags)
+        metadata = os.fstat(fd)
+        if (
+            not stat.S_ISREG(metadata.st_mode)
+            or metadata.st_nlink != 1
+            or metadata.st_size > BASH_REFERENCE_POLICY_MAX_BYTES
+        ):
+            return None
+        source = os.read(fd, BASH_REFERENCE_POLICY_MAX_BYTES + 1)
+        if len(source) > BASH_REFERENCE_POLICY_MAX_BYTES:
+            return None
+        source_text = source.decode("utf-8", errors="strict")
+    except (OSError, UnicodeDecodeError):
+        return None
+    finally:
+        if fd >= 0:
+            os.close(fd)
+    module_name = f"_context_guard_setup_reference_policy_{os.getpid()}"
+    module = types.ModuleType(module_name)
+    module.__file__ = str(path)
+    module.__package__ = ""
+    sys.modules[module_name] = module
+    try:
+        exec(compile(source_text, str(path), "exec"), module.__dict__)
+    except Exception:
+        sys.modules.pop(module_name, None)
+        return None
+    return module
+
+
+def bash_reference_adapter_readiness(root: Path) -> tuple[bool, str]:
+    """Return the runtime adapter verdict for the effective setup project."""
+    policy = load_bash_reference_policy()
+    discover = getattr(policy, "discover_adapter", None)
+    if policy is None:
+        return False, "receipt_policy_unavailable"
+    if not callable(discover):
+        return False, "receipt_policy_invalid"
+    try:
+        discovered = discover(root)
+    except Exception:
+        return False, "receipt_policy_load_failed"
+    if not isinstance(discovered, tuple) or len(discovered) != 2:
+        return False, "receipt_policy_invalid"
+    adapter, reason = discovered
+    adapter_methods = ("start_broker", "query_reference")
+    if (
+        adapter is not None
+        and reason == "receipt_adapter_available"
+        and all(callable(getattr(adapter, name, None)) for name in adapter_methods)
+    ):
+        return True, reason
+    if adapter is not None and reason == "receipt_adapter_available":
+        return False, "receipt_adapter_invalid"
+    if not isinstance(reason, str) or re.fullmatch(r"[a-z0-9_]{1,96}", reason) is None:
+        return False, "receipt_policy_invalid"
+    return False, reason
+
+
+def bash_reference_unavailable_message(reason: str) -> str:
+    return (
+        f"{_BASH_REFERENCE_UNAVAILABLE}: reason={reason}; requires an exact paired npm install "
+        f"of {ROOT_PACKAGE_NAME} and {RECEIPT_PACKAGE_NAME}; "
+        f"recovery={_BASH_REFERENCE_RECOVERY}; ordinary Bash trimming remains enabled"
+    )
+
+
+def disable_unavailable_bash_reference(
+    choices: Choices,
+    warnings: list[str],
+    *,
+    root: Path,
+) -> list[str]:
+    """Fail closed without removing the ordinary Bash trimming choice."""
+    if not choices.bash_reference_v1:
+        return []
+    available, reason = bash_reference_adapter_readiness(root)
+    if available:
+        return []
+    choices.bash_reference_v1 = False
+    warning = bash_reference_unavailable_message(reason)
+    warnings.append(warning)
+    return [warning]
+
+
+def read_hook_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
+    return {
+        "matcher": "Read",
+        "hooks": [{"type": "command", "command": automatic_helper_command(
+            HELPER_GUARD_READ,
+            "guard_large_read.py",
+            allow_path_fallback=allow_path_fallback,
+            preserve_env_names=READ_GUARD_BEHAVIOR_ENV,
+        )}],
+    }
+
+
+def failed_nudge_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
+    return {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": automatic_helper_command(HELPER_FAILED_NUDGE, "failed_attempt_nudge.py", allow_path_fallback=allow_path_fallback)}],
+    }
+
+
+def command_matches(existing: str, desired: str) -> bool:
+    if existing == desired:
+        return True
+    try:
+        existing_parts = shlex.split(existing) if existing else []
+        desired_parts = shlex.split(desired) if desired else []
+    except ValueError:
+        return False
+    return bool(existing_parts and desired_parts and existing_parts == desired_parts)
+
+
+def command_helper_basenames(command: str) -> set[str]:
+    try:
+        parts = shlex.split(command) if command else []
+    except ValueError:
+        return set()
+    if not parts:
+        return set()
+    index = 0
+    if os.path.basename(parts[index]) == "env":
+        index += 1
+        while index < len(parts):
+            token = parts[index]
+            if token in {"-i", "--ignore-environment"}:
+                index += 1
+                continue
+            if token in {"-u", "--unset"} and index + 1 < len(parts):
+                index += 2
+                continue
+            if token.startswith("--unset="):
+                index += 1
+                continue
+            break
+        while index < len(parts) and "=" in parts[index] and not parts[index].startswith("-"):
+            index += 1
+    if index >= len(parts):
+        return set()
+    head = os.path.basename(parts[index])
+    interpreter_heads = {"bash", "sh"}
+    if re.fullmatch(r"python(?:\d+(?:\.\d+)?)?", head):
+        interpreter_heads.add(head)
+    if head in interpreter_heads:
+        for token_index in range(index + 1, len(parts)):
+            token = parts[token_index]
+            if token == "-c":
+                if token_index + 1 < len(parts):
+                    return command_helper_basenames(parts[token_index + 1])
+                return set()
+            if token.startswith("-"):
+                continue
+            return {os.path.basename(token)}
+        return set()
+    return {head}
+
+
+def _statusline_candidate_paths(*, merged: bool) -> set[Path]:
+    script_dir = Path(__file__).resolve().parent
+    helper_key = HELPER_STATUSLINE if merged else HELPER_STATUSLINE_PLAIN
+    kit_script = "statusline_merged.sh" if merged else "statusline.sh"
+    names = HELPER_EQUIVALENT_BASENAMES[helper_key]
+    raw_candidates = {script_dir / kit_script}
+    for name in names:
+        raw_candidates.add(script_dir / name)
+        raw_candidates.add(
+            script_dir.parent / "plugins" / "context-guard" / "bin" / name
+        )
+    candidates: set[Path] = set()
+    for candidate in raw_candidates:
+        try:
+            candidates.add(candidate.resolve(strict=True))
+        except OSError:
+            continue
+    return candidates
+
+
+def _authenticated_statusline_path(raw: str, *, merged: bool) -> Path | None:
+    candidate = Path(raw)
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+    try:
+        canonical = candidate.resolve(strict=True)
+    except OSError:
+        return None
+    return canonical if canonical in _statusline_candidate_paths(merged=merged) else None
+
+
+def exact_known_statusline_command(command: str) -> bool:
+    """Match only authenticated complete historical merged-statusline commands."""
+    try:
+        parts = shlex.split(command) if command else []
+    except ValueError:
+        return False
+    if not parts:
+        return False
+    known_helpers = HELPER_EQUIVALENT_BASENAMES[HELPER_STATUSLINE]
+    direct_head = parts[0]
+    if len(parts) == 1:
+        if direct_head in known_helpers:
+            return True
+        return _authenticated_statusline_path(direct_head, merged=True) is not None
+
+    index = 0
+    generated_shape = False
+    assignments: dict[str, str] = {}
+    approved_env = str(_approved_system_runtime("env"))
+    if direct_head == approved_env:
+        generated_shape = True
+        index += 1
+        if index >= len(parts) or parts[index] != "-i":
+            return False
+        index += 1
+        allowed_assignments = {
+            "PATH",
+            "LC_ALL",
+            "HOME",
+            *STATUSLINE_BEHAVIOR_ENV,
+        }
+        while index < len(parts) and "=" in parts[index] and not parts[index].startswith("-"):
+            name, _separator, value = parts[index].partition("=")
+            if name not in allowed_assignments or name in assignments:
+                return False
+            assignments[name] = value
+            index += 1
+        if assignments.get("PATH") != ISOLATED_RUNTIME_PATH or assignments.get("LC_ALL") != "C":
+            return False
+        for name, value in assignments.items():
+            if name in STATUSLINE_BEHAVIOR_ENV and not BEHAVIOR_ENV_VALUE_RE.fullmatch(value):
+                return False
+
+    approved_bash = str(_approved_system_runtime("bash"))
+    if index >= len(parts):
+        return False
+    shell = parts[index]
+    if generated_shape:
+        if shell != approved_bash:
+            return False
+    elif shell not in {"bash", "sh", approved_bash}:
+        return False
+    index += 1
+    if generated_shape:
+        if parts[index : index + 2] != ["--noprofile", "--norc"]:
+            return False
+        index += 2
+    else:
+        while index < len(parts) and parts[index] in {"--noprofile", "--norc"}:
+            index += 1
+    if index >= len(parts):
+        return False
+    if _authenticated_statusline_path(parts[index], merged=True) is None:
+        return False
+    index += 1
+    if not generated_shape:
+        return index == len(parts)
+
+    required_prefix = [
+        "--approved-bash",
+        approved_bash,
+        "--approved-python",
+        str(_approved_python_runtime()),
+        "--approved-token-statusline",
+    ]
+    if parts[index : index + len(required_prefix)] != required_prefix:
+        return False
+    index += len(required_prefix)
+    if index >= len(parts):
+        return False
+    if _authenticated_statusline_path(parts[index], merged=False) is None:
+        return False
+    index += 1
+
+    approved_omc = _approved_default_omc_hud()
+    if index == len(parts):
+        return "HOME" not in assignments
+    if approved_omc is None or len(parts) - index != 4:
+        return False
+    node_runtime, omc_script = approved_omc
+    expected_omc = [
+        "--approved-node",
+        str(node_runtime),
+        "--approved-omc-script",
+        str(omc_script),
+    ]
+    return (
+        parts[index:] == expected_omc
+        and assignments.get("HOME") == str(omc_script.parents[2])
+    )
+
+
+def equivalent_helper_basenames(command: str) -> set[str]:
+    bases = command_helper_basenames(command)
+    equivalents = set(bases)
+    for base in bases:
+        equivalents.update(HELPER_EQUIVALENT_BASENAMES.get(base, ()))
+    return equivalents
+
+
+def _generic_hook_spec(desired: str) -> tuple[str, str, tuple[str, ...]] | None:
+    desired_bases = command_helper_basenames(desired)
+    specs = (
+        (HELPER_REWRITE_BASH, "rewrite_bash_for_token_budget.py", REWRITE_BEHAVIOR_ENV),
+        (HELPER_GUARD_READ, "guard_large_read.py", READ_GUARD_BEHAVIOR_ENV),
+        (HELPER_FAILED_NUDGE, "failed_attempt_nudge.py", ()),
+    )
+    for helper_name, kit_script, behavior_env in specs:
+        if desired_bases & HELPER_EQUIVALENT_BASENAMES[helper_name]:
+            return helper_name, kit_script, behavior_env
+    return None
+
+
+def _generic_hook_candidate_paths(helper_name: str, kit_script: str) -> set[Path]:
+    script_dir = Path(__file__).resolve().parent
+    raw_candidates = {script_dir / kit_script}
+    for name in HELPER_EQUIVALENT_BASENAMES[helper_name]:
+        raw_candidates.add(script_dir / name)
+        raw_candidates.add(
+            script_dir.parent / "plugins" / "context-guard" / "bin" / name
+        )
+    candidates: set[Path] = set()
+    for candidate in raw_candidates:
+        try:
+            candidates.add(candidate.resolve(strict=True))
+        except OSError:
+            continue
+    return candidates
+
+
+def _authenticated_generic_hook_path(
+    raw: str,
+    *,
+    helper_name: str,
+    kit_script: str,
+) -> Path | None:
+    candidate = Path(raw)
+    if not candidate.is_absolute():
+        candidate = Path.cwd() / candidate
+    try:
+        canonical = candidate.resolve(strict=True)
+    except OSError:
+        return None
+    candidates = _generic_hook_candidate_paths(helper_name, kit_script)
+    return canonical if canonical in candidates else None
+
+
+def exact_known_hook_command(existing: str, desired: str) -> bool:
     if command_matches(existing, desired):
         return True
-    desired_helpers = equivalent_helper_basenames(desired)
-    if not desired_helpers:
+    spec = _generic_hook_spec(desired)
+    if spec is None:
+        return False
+    helper_name, kit_script, behavior_env = spec
+    known_names = HELPER_EQUIVALENT_BASENAMES[helper_name]
+    try:
+        parts = shlex.split(existing) if existing else []
+    except ValueError:
+        return False
+    if not parts:
+        return False
+    if len(parts) == 1:
+        if parts[0] in known_names:
+            return True
+        return _authenticated_generic_hook_path(
+            parts[0],
+            helper_name=helper_name,
+            kit_script=kit_script,
+        ) is not None
+
+    index = 0
+    generated_shape = parts[0] == str(_approved_system_runtime("env"))
+    if generated_shape:
+        index = 1
+        if index >= len(parts) or parts[index] != "-i":
+            return False
+        index += 1
+        assignments: dict[str, str] = {}
+        allowed_assignments = {"PATH", "LC_ALL", *behavior_env}
+        while index < len(parts) and "=" in parts[index] and not parts[index].startswith("-"):
+            name, _separator, value = parts[index].partition("=")
+            if name not in allowed_assignments or name in assignments:
+                return False
+            assignments[name] = value
+            index += 1
+        if assignments.get("PATH") != ISOLATED_RUNTIME_PATH or assignments.get("LC_ALL") != "C":
+            return False
+        for name, value in assignments.items():
+            if name in behavior_env and not BEHAVIOR_ENV_VALUE_RE.fullmatch(value):
+                return False
+
+    if index >= len(parts):
+        return False
+    python_runtime = parts[index]
+    if generated_shape:
+        if python_runtime != str(_approved_python_runtime()):
+            return False
+    elif (
+        "/" in python_runtime
+        or re.fullmatch(r"python(?:\d+(?:\.\d+)?)?", python_runtime) is None
+    ):
+        return False
+    index += 1
+    if index < len(parts) and parts[index] == "-I":
+        index += 1
+    elif generated_shape:
         return False
-    return bool(command_helper_basenames(existing) & desired_helpers)
+    if index >= len(parts):
+        return False
+    if _authenticated_generic_hook_path(
+        parts[index],
+        helper_name=helper_name,
+        kit_script=kit_script,
+    ) is None:
+        return False
+    index += 1
+    if index == len(parts):
+        return True
+    return (
+        helper_name == HELPER_REWRITE_BASH
+        and parts[index:] == ["--bash-reference-v1"]
+    )
+
+
+def command_matches_existing_or_equivalent(existing: str, desired: str) -> bool:
+    return exact_known_hook_command(existing, desired)
 
 
 def canonicalize_equivalent_command(value: Any, desired: str) -> tuple[bool, bool]:
@@ -1649,6 +2826,16 @@ def ensure_post_tool_hook(settings: dict[str, Any], hook: dict[str, Any], comman
     _ensure_tool_hook(settings, hook, command, label, actions, event="PostToolUse")
 
 
+def ensure_post_tool_failure_hook(
+    settings: dict[str, Any],
+    hook: dict[str, Any],
+    command: str,
+    label: str,
+    actions: list[str],
+) -> None:
+    _ensure_tool_hook(settings, hook, command, label, actions, event="PostToolUseFailure")
+
+
 def _ensure_tool_hook(
     settings: dict[str, Any],
     hook: dict[str, Any],
@@ -1973,7 +3160,28 @@ def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
         }
 
     choices = choices_from_args(args)
-    actions = apply_choices(settings, choices, allow_path_fallback=bool(getattr(args, "allow_path_helper_fallback", False))) if claude_targeted else []
+    reference_actions = disable_unavailable_bash_reference(
+        choices,
+        warnings,
+        root=root,
+    )
+    if reference_actions:
+        checks.append(doctor_check(
+            "bash-reference-distribution",
+            "warning",
+            "medium",
+            reference_actions[0],
+            next_action=_BASH_REFERENCE_RECOVERY + ".",
+        ))
+    actions = reference_actions + (
+        apply_choices(
+            settings,
+            choices,
+            allow_path_fallback=bool(getattr(args, "allow_path_helper_fallback", False)),
+        )
+        if claude_targeted
+        else []
+    )
     changed = (settings != original) if claude_targeted else False
     if changed:
         checks.append(doctor_check(
@@ -2129,18 +3337,46 @@ def apply_choices(settings: dict[str, Any], choices: Choices, *, allow_path_fall
             settings["effortLevel"] = DEFAULT_EFFORT
             actions.append(f"set default effortLevel to {DEFAULT_EFFORT}")
     if choices.statusline:
-        statusline = statusline_setting(allow_path_fallback=allow_path_fallback)
+        statusline, omc_included = _statusline_setting(allow_path_fallback=allow_path_fallback)
         if "statusLine" not in settings:
             settings["statusLine"] = statusline
             actions.append("enabled token statusline")
+            if omc_included:
+                actions.append("included setup-approved OMC HUD")
         elif settings.get("statusLine") != statusline:
-            actions.append("kept existing statusLine; add context-guard-statusline-merged manually if desired")
+            existing_statusline = settings.get("statusLine")
+            existing_command = (
+                existing_statusline.get("command")
+                if isinstance(existing_statusline, dict)
+                else None
+            )
+            if (
+                isinstance(existing_command, str)
+                and exact_known_statusline_command(existing_command)
+            ):
+                settings["statusLine"] = statusline
+                actions.append("migrated token statusline")
+                if omc_included:
+                    actions.append("included setup-approved OMC HUD")
+            else:
+                actions.append("kept existing statusLine; add context-guard-statusline-merged manually if desired")
     if choices.denies:
-        ensure_permissions(settings, actions)
+        ensure_permissions(
+            settings,
+            actions,
+            migrate_env_read_denies=choices.read_guard,
+        )
     if choices.bash_hook:
-        bash_hook = bash_hook_setting(allow_path_fallback=allow_path_fallback)
+        bash_hook = bash_hook_setting(
+            allow_path_fallback=allow_path_fallback,
+            bash_reference_v1=choices.bash_reference_v1,
+        )
         bash_command = bash_hook["hooks"][0]["command"]
         ensure_pre_tool_hook(settings, bash_hook, bash_command, "Bash trim/sanitize", actions)
+        if choices.bash_reference_v1:
+            actions.append(
+                "enabled bash_reference_v1: a scoped 7-day bearer handle may appear in Claude/provider-visible transcripts"
+            )
     if choices.read_guard:
         read_hook = read_hook_setting(allow_path_fallback=allow_path_fallback)
         read_command = read_hook["hooks"][0]["command"]
@@ -2149,10 +3385,24 @@ def apply_choices(settings: dict[str, Any], choices: Choices, *, allow_path_fall
         nudge_hook = failed_nudge_setting(allow_path_fallback=allow_path_fallback)
         nudge_command = nudge_hook["hooks"][0]["command"]
         ensure_post_tool_hook(settings, nudge_hook, nudge_command, "failed-attempt /clear nudge", actions)
+        ensure_post_tool_failure_hook(
+            settings,
+            nudge_hook,
+            nudge_command,
+            "failed-attempt /clear nudge",
+            actions,
+        )
     return actions
 
 
-def atomic_write(path: Path, text: str, mode: int = 0o600, *, dir_mode: int = PRIVATE_DIR_MODE) -> None:
+def atomic_write_bytes(
+    path: Path,
+    data: bytes,
+    mode: int = 0o600,
+    *,
+    dir_mode: int = PRIVATE_DIR_MODE,
+    expected: ManagedFileSnapshot | None = None,
+) -> None:
     if os.rename not in os.supports_dir_fd or os.unlink not in os.supports_dir_fd:
         raise OSError("platform does not support directory-relative atomic writes")
     parent_fd = _ensure_directory_no_symlink(path.parent, dir_mode, parents_mode=dir_mode)
@@ -2162,12 +3412,14 @@ def atomic_write(path: Path, text: str, mode: int = 0o600, *, dir_mode: int = PR
     try:
         if hasattr(os, "fchmod"):
             os.fchmod(fd, mode)
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
+        with os.fdopen(fd, "wb") as f:
             fd = -1
-            f.write(text)
+            f.write(data)
             f.flush()
             os.fsync(f.fileno())
         os.fsync(parent_fd)
+        if expected is not None:
+            _verify_expected_snapshot(path, expected)
         os.rename(tmp_name, path.name, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
         try:
             os.fsync(parent_fd)
@@ -2185,6 +3437,37 @@ def atomic_write(path: Path, text: str, mode: int = 0o600, *, dir_mode: int = PR
         os.close(parent_fd)
 
 
+def atomic_write(
+    path: Path,
+    content: str | bytes,
+    mode: int = 0o600,
+    *,
+    dir_mode: int = PRIVATE_DIR_MODE,
+) -> None:
+    data = content if isinstance(content, bytes) else content.encode("utf-8")
+    atomic_write_bytes(path, data, mode, dir_mode=dir_mode)
+
+
+def _atomic_remove_expected(
+    path: Path,
+    expected: ManagedFileSnapshot,
+    *,
+    dir_mode: int,
+) -> None:
+    parent_fd = _ensure_directory_no_symlink(path.parent, dir_mode, parents_mode=dir_mode)
+    try:
+        _verify_expected_snapshot(path, expected)
+        os.unlink(path.name, dir_fd=parent_fd)
+        try:
+            os.fsync(parent_fd)
+        except OSError as exc:
+            raise AtomicWriteDurabilityError(
+                f"remove committed but parent directory durability is uncertain: {path}"
+            ) from exc
+    finally:
+        os.close(parent_fd)
+
+
 def existing_mode_or_default(path: Path, default: int = 0o600) -> int:
     try:
         fd = _open_regular_no_symlink(path)
@@ -2210,6 +3493,175 @@ def backup_existing(path: Path) -> Path | None:
     return backup
 
 
+def managed_lock_path(path: Path) -> Path:
+    return path.with_name(f".{path.name}.lock")
+
+
+def acquire_managed_file_lock(path: Path, *, dir_mode: int = PRIVATE_DIR_MODE) -> int:
+    """Acquire the shared sibling lock used by all managed forward/rollback writers."""
+    if fcntl is None:
+        raise OSError("platform does not support advisory file locks")
+    parent_fd = _ensure_directory_no_symlink(path.parent, dir_mode, parents_mode=dir_mode)
+    lock_name = managed_lock_path(path).name
+    flags = os.O_CREAT | os.O_RDWR | _no_follow_flag()
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    fd: int | None = None
+    try:
+        for attempt in range(3):
+            try:
+                fd = os.open(lock_name, flags, 0o600, dir_fd=parent_fd)
+                break
+            except FileNotFoundError:
+                if attempt == 2:
+                    raise
+                time.sleep(0.001)
+    except OSError as exc:
+        raise OSError(f"could not open cooperative lock {managed_lock_path(path)}: {exc}") from exc
+    finally:
+        os.close(parent_fd)
+    if fd is None:
+        raise OSError(f"could not open cooperative lock {managed_lock_path(path)}")
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode):
+            raise OSError(f"cooperative lock is not a regular file: {managed_lock_path(path)}")
+        if hasattr(os, "fchmod"):
+            os.fchmod(fd, 0o600)
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        return fd
+    except Exception:
+        os.close(fd)
+        raise
+
+
+def release_managed_file_lock(fd: int) -> None:
+    try:
+        if fcntl is not None:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+
+
+def _managed_backup(path: Path, data: bytes, *, dir_mode: int) -> Path:
+    stamp = _dt.datetime.now().strftime("%Y%m%d%H%M%S%f")
+    backup = path.with_name(f"{path.name}.bak-{stamp}-{uuid.uuid4().hex[:8]}")
+    atomic_write_bytes(backup, data, 0o600, dir_mode=dir_mode)
+    return backup
+
+
+def write_managed_file(
+    path: Path,
+    *,
+    expected: ManagedFileSnapshot,
+    desired: bytes | None,
+    mode: int = 0o644,
+    dir_mode: int = 0o755,
+    create_backup: bool = True,
+    prepare_commit: Any = None,
+) -> dict[str, Any]:
+    """Apply one cooperative byte-exact transaction or return a fail-closed status."""
+    if desired == expected.data:
+        return {"status": "unchanged", "backup_path": None}
+    try:
+        lock_fd = acquire_managed_file_lock(path, dir_mode=dir_mode)
+    except OSError as exc:
+        return {"status": "skipped", "reason": f"could not acquire cooperative lock: {exc}"}
+    backup_path: Path | None = None
+    try:
+        try:
+            current = _verify_expected_snapshot(path, expected)
+        except ManagedFileConflictError as exc:
+            return {"status": "conflict", "reason": str(exc), "backup_path": None}
+
+        target_mode = mode
+        if current.metadata is not None:
+            target_mode = stat.S_IMODE(current.metadata[2])
+        if current.data is not None and create_backup:
+            try:
+                backup_path = _managed_backup(path, current.data, dir_mode=dir_mode)
+            except OSError as exc:
+                return {
+                    "status": "skipped",
+                    "reason": f"could not create private managed-file backup: {exc}",
+                    "backup_path": None,
+                }
+        try:
+            if desired is None:
+                if prepare_commit is not None:
+                    prepare_commit(backup_path)
+                _atomic_remove_expected(path, current, dir_mode=dir_mode)
+            else:
+                _verify_expected_snapshot(path, current)
+                if prepare_commit is not None:
+                    prepare_commit(backup_path)
+                atomic_write(
+                    path,
+                    desired,
+                    target_mode,
+                    dir_mode=dir_mode,
+                )
+        except ManagedFileConflictError as exc:
+            return {
+                "status": "conflict",
+                "reason": str(exc),
+                "backup_path": str(backup_path) if backup_path else None,
+            }
+        except AtomicWriteDurabilityError as exc:
+            return {
+                "status": "applied-durability-uncertain",
+                "reason": str(exc),
+                "backup_path": str(backup_path) if backup_path else None,
+                "residual_risk": (
+                    "A non-cooperating editor can still race after the final comparison; "
+                    "automatic follow-on mutation is blocked."
+                ),
+            }
+        except OSError as exc:
+            return {
+                "status": "skipped",
+                "reason": f"could not commit managed file: {exc}",
+                "backup_path": str(backup_path) if backup_path else None,
+            }
+        return {
+            "status": "applied",
+            "backup_path": str(backup_path) if backup_path else None,
+            "residual_risk": (
+                "Cooperating ContextGuard writers serialize; a non-cooperating editor can still race "
+                "after the final comparison and before atomic replace."
+            ),
+        }
+    finally:
+        release_managed_file_lock(lock_fd)
+
+
+def rollback_managed_file(
+    path: Path,
+    *,
+    expected_post: ManagedFileSnapshot,
+    restore: bytes | None,
+    kind: str,
+    mode: int = 0o644,
+    dir_mode: int = 0o755,
+) -> dict[str, Any]:
+    """Rollback only a still-matching post-image with the same parser/lock authority."""
+    if expected_post.data is None:
+        return {"status": "skipped", "reason": "rollback post-image is missing"}
+    ownership = parse_managed_bytes(expected_post.data, kind=kind)
+    if ownership.status != "valid":
+        return {
+            "status": "skipped",
+            "reason": f"rollback lacks valid {kind} ownership: {ownership.status}",
+        }
+    return write_managed_file(
+        path,
+        expected=expected_post,
+        desired=restore,
+        mode=mode,
+        dir_mode=dir_mode,
+    )
+
+
 def rollback_restore_guidance(settings_path: Path, backup_path: Path | None, original_existed: bool) -> str:
     if backup_path is not None:
         return (
@@ -2317,10 +3769,14 @@ def interactive_choices(defaults: Choices) -> Choices:
         denies=prompt_bool("Add deny rules for bulky/sensitive paths?", defaults.denies),
         statusline=prompt_bool("Enable token/cost statusline?", defaults.statusline),
         bash_hook=prompt_bool("Enable Bash output trim + grep/diff sanitizer hook?", defaults.bash_hook),
+        bash_reference_v1=prompt_bool(
+            "Enable optional Bash receipt references? 7-day scoped bearer handles are visible to Claude/provider transcripts",
+            defaults.bash_reference_v1,
+        ),
         read_guard=prompt_bool("Enable large Read guard?", defaults.read_guard),
         model_defaults=prompt_bool("Set missing defaults to model=sonnet and effortLevel=medium?", defaults.model_defaults),
         failed_attempt_nudge=prompt_bool(
-            "Enable failed-attempt /clear nudge? (PostToolUse hook on Bash; recommended default)",
+            "Enable failed-attempt /clear nudge? (Bash terminal-event hooks; recommended default)",
             defaults.failed_attempt_nudge,
         ),
     )
@@ -2332,6 +3788,7 @@ def choices_from_args(args: argparse.Namespace) -> Choices:
         denies=not args.no_denies,
         statusline=not args.no_statusline,
         bash_hook=not args.no_bash_hook,
+        bash_reference_v1=getattr(args, "bash_reference_v1", False),
         read_guard=not args.no_read_guard,
         model_defaults=not args.no_model_defaults,
         failed_attempt_nudge=(
@@ -2396,6 +3853,201 @@ def render_text(result: SetupResult) -> str:
     return "\n".join(lines) + "\n"
 
 
+def validate_rules_only_args(parser: argparse.ArgumentParser, args: argparse.Namespace) -> bool:
+    """Validate and identify the isolated Claude quiet-narration CLI branch."""
+    rules_only = bool(getattr(args, "rules_only", False))
+    narration_mode = getattr(args, "narration_mode", None)
+    if narration_mode and not rules_only:
+        parser.error("--narration-mode requires --rules-only")
+    if rules_only and not narration_mode:
+        parser.error("--rules-only requires a rule operation such as --narration-mode")
+    if not rules_only:
+        return False
+
+    if getattr(args, "scope", "project") != "project":
+        parser.error("quiet narration rules support only --scope project")
+    selected = [item.lower() for item in (explicit_agent_selection(args) or [])]
+    if selected != ["claude"] or not getattr(args, "agent", None) or getattr(args, "only", None):
+        parser.error("quiet narration rules require exactly one explicit --agent claude")
+    action_count = sum(
+        bool(value)
+        for value in (
+            getattr(args, "yes", False),
+            getattr(args, "plan", False),
+            getattr(args, "dry_run", False),
+        )
+    )
+    if action_count != 1:
+        parser.error("quiet narration rules require exactly one of --plan, --dry-run, or --yes")
+
+    conflicting = [
+        flag
+        for attr, flag in (
+            ("allow_home_settings", "--allow-home-settings"),
+            ("verify", "--verify"),
+            ("no_backup", "--no-backup"),
+            ("no_denies", "--no-denies"),
+            ("no_statusline", "--no-statusline"),
+            ("no_bash_hook", "--no-bash-hook"),
+            ("no_read_guard", "--no-read-guard"),
+            ("no_model_defaults", "--no-model-defaults"),
+            ("no_diet_scan", "--no-diet-scan"),
+            ("allow_path_helper_fallback", "--allow-path-helper-fallback"),
+            ("with_init", "--with-init"),
+            ("with_skill", "--with-skill"),
+            ("brief_mode", "--brief-mode"),
+            ("list_adapters", "--list-adapters"),
+        )
+        if getattr(args, attr, False)
+    ]
+    if getattr(args, "failed_attempt_nudge", None) is not None:
+        conflicting.append(
+            "--failed-attempt-nudge"
+            if args.failed_attempt_nudge
+            else "--no-failed-attempt-nudge"
+        )
+    if conflicting:
+        parser.error(
+            "quiet narration rules cannot be combined with settings, hook, adapter, "
+            f"or setup flags: {', '.join(conflicting)}"
+        )
+    return True
+
+
+def run_quiet_narration_rules(args: argparse.Namespace) -> dict[str, Any]:
+    """Plan/apply the isolated Claude/project CLAUDE.md narration span."""
+    require_no_follow_file_ops_supported()
+    root = resolve_setup_root(args.root)
+    rule_path = root / "CLAUDE.md"
+    state = _rule_file_state(rule_path)
+    if state["status"] not in {"missing", "file"}:
+        raise SystemExit(
+            state.get("reason")
+            or f"refused unsafe quiet narration rule target: {rule_path}"
+        )
+    existing = bytes(state.get("bytes") or b"")
+    parsed = parse_managed_bytes(existing, kind="narration-mode")
+    if parsed.status not in {"absent", "valid"}:
+        raise SystemExit(
+            f"refused unsafe managed narration state in {rule_path.name}: "
+            f"{parsed.reason or parsed.status}"
+        )
+
+    mode = str(args.narration_mode)
+    span = parsed.spans[0] if parsed.status == "valid" else None
+    desired = existing
+    if mode == "quiet":
+        block = _managed_block_bytes(render_quiet_narration_block())
+        if span is None:
+            desired = _append_narration_block_bytes(existing, block)
+        elif existing[span.start : span.end] != block:
+            desired = _replace_managed_span(existing, span, block)
+    elif span is not None:
+        removal_start = span.start
+        if removal_start > 0 and existing[removal_start - 1 : removal_start] == b"\n":
+            removal_start -= 1
+        desired = existing[:removal_start] + existing[span.end :]
+
+    changed = desired != existing
+    apply_requested = bool(args.yes)
+    if not changed:
+        status = "exists" if mode == "quiet" else "absent"
+        return {
+            "schema_version": "contextguard.narration-rules.v1",
+            "operation": "quiet-narration",
+            "mode": mode,
+            "root": str(root),
+            "rule_file": str(rule_path),
+            "marker_state_before": parsed.status,
+            "status": status,
+            "changed": False,
+            "applied": False,
+            "apply_requested": apply_requested,
+            "backup_path": None,
+            "actions": [
+                "quiet narration rules already present"
+                if mode == "quiet"
+                else "quiet narration rules already absent"
+            ],
+            "claim_boundary": "static setup result only; no model-compliance or savings claim",
+        }
+
+    planned_status = "planned"
+    action = (
+        ("add" if span is None else "refresh") + " quiet narration rules"
+        if mode == "quiet"
+        else "remove quiet narration rules"
+    )
+    if not apply_requested:
+        return {
+            "schema_version": "contextguard.narration-rules.v1",
+            "operation": "quiet-narration",
+            "mode": mode,
+            "root": str(root),
+            "rule_file": str(rule_path),
+            "marker_state_before": parsed.status,
+            "status": planned_status,
+            "changed": True,
+            "applied": False,
+            "apply_requested": False,
+            "backup_path": None,
+            "actions": [f"would {action}"],
+            "claim_boundary": "static setup result only; no model-compliance or savings claim",
+        }
+
+    write_result = write_managed_file(
+        rule_path,
+        expected=state["snapshot"],
+        desired=desired,
+        mode=existing_mode_or_default(rule_path, 0o644),
+        dir_mode=0o755,
+    )
+    if write_result["status"] not in {"applied", "applied-durability-uncertain"}:
+        raise SystemExit(
+            write_result.get("reason")
+            or f"could not safely update quiet narration rules in {rule_path}"
+        )
+    status = (
+        write_result["status"]
+        if write_result["status"] == "applied-durability-uncertain"
+        else ("removed" if mode == "default" else ("applied" if span is None else "updated"))
+    )
+    payload = {
+        "schema_version": "contextguard.narration-rules.v1",
+        "operation": "quiet-narration",
+        "mode": mode,
+        "root": str(root),
+        "rule_file": str(rule_path),
+        "marker_state_before": parsed.status,
+        "status": status,
+        "changed": True,
+        "applied": True,
+        "apply_requested": True,
+        "backup_path": write_result.get("backup_path"),
+        "actions": [action],
+        "claim_boundary": "static setup result only; no model-compliance or savings claim",
+    }
+    if write_result.get("reason"):
+        payload["warning"] = write_result["reason"]
+    if write_result.get("residual_risk"):
+        payload["residual_risk"] = write_result["residual_risk"]
+    return payload
+
+
+def render_quiet_narration_text(result: dict[str, Any]) -> str:
+    lines = [
+        f"ContextGuard quiet narration ({result['status']})",
+        f"root={result['root']}",
+        f"rule_file={result['rule_file']}",
+        f"mode={result['mode']}",
+    ]
+    if result.get("backup_path"):
+        lines.append(f"backup={result['backup_path']}")
+    lines.extend(f"- {action}" for action in result.get("actions", []))
+    lines.append(str(result["claim_boundary"]))
+    return "\n".join(lines) + "\n"
+
+
 def run(args: argparse.Namespace) -> SetupResult:
     require_no_follow_file_ops_supported()
     scope = normalize_scope(getattr(args, "scope", "project"))
@@ -2416,10 +4068,21 @@ def run(args: argparse.Namespace) -> SetupResult:
     if claude_targeted:
         validate_settings_target(root, settings_path, allow_home_settings=(args.allow_home_settings or scope == "user"))
         original_text = _read_optional_text_no_follow(settings_path)
+        settings_snapshot = read_managed_file_snapshot(settings_path)
+        snapshot_text = (
+            settings_snapshot.data.decode("utf-8")
+            if settings_snapshot.data is not None
+            else None
+        )
+        if snapshot_text != original_text:
+            raise SystemExit(
+                f"Settings changed while setup was preparing changes; re-run setup to merge latest file: {settings_path}"
+            )
         original = _parse_json_object_text(original_text, settings_path)
         settings = json.loads(json.dumps(original))
     else:
         original_text = None
+        settings_snapshot = ManagedFileSnapshot(None, None)
         original = {}
         settings = {}
 
@@ -2434,7 +4097,20 @@ def run(args: argparse.Namespace) -> SetupResult:
     if interactive:
         choices = interactive_choices(choices)
 
-    actions = apply_choices(settings, choices, allow_path_fallback=bool(getattr(args, "allow_path_helper_fallback", False))) if claude_targeted else []
+    reference_actions = disable_unavailable_bash_reference(
+        choices,
+        warnings,
+        root=root,
+    )
+    actions = reference_actions + (
+        apply_choices(
+            settings,
+            choices,
+            allow_path_fallback=bool(getattr(args, "allow_path_helper_fallback", False)),
+        )
+        if claude_targeted
+        else []
+    )
     changed = (settings != original) if claude_targeted else False
 
     apply_requested = bool(args.yes and not args.dry_run and not args.plan)
@@ -2471,31 +4147,45 @@ def run(args: argparse.Namespace) -> SetupResult:
     if claude_targeted and apply_requested and changed:
         if scope == "user" and original_text is not None and args.no_backup:
             raise SystemExit("Refusing --no-backup for user-scope changes to existing Claude settings.")
-        lock_fd = acquire_settings_lock(settings_path)
-        try:
-            current_text = _read_optional_text_no_follow(settings_path)
-            if current_text != original_text:
-                raise SystemExit(
-                    f"Settings changed while setup was preparing changes; re-run setup to merge latest file: {settings_path}"
-                )
-            if original_text is not None and not args.no_backup and settings != original:
-                backup_path = backup_existing(settings_path)
-            if settings != original:
-                rollback_id, rollback_path = write_rollback_record(
-                    root=root,
-                    scope=scope,
-                    settings_path=settings_path,
-                    backup_path=backup_path,
-                    original_existed=(original_text is not None),
-                )
-                atomic_write(
-                    settings_path,
-                    json.dumps(settings, indent=2, sort_keys=True) + "\n",
-                    existing_mode_or_default(settings_path, 0o600),
-                )
-                claude_settings_written = True
-        finally:
-            release_settings_lock(lock_fd)
+        rollback_state: dict[str, Any] = {}
+
+        def prepare_settings_commit(managed_backup_path: Path | None) -> None:
+            prepared_rollback_id, prepared_rollback_path = write_rollback_record(
+                root=root,
+                scope=scope,
+                settings_path=settings_path,
+                backup_path=managed_backup_path,
+                original_existed=(original_text is not None),
+            )
+            rollback_state.update({
+                "rollback_id": prepared_rollback_id,
+                "rollback_path": prepared_rollback_path,
+            })
+
+        desired_settings = (
+            json.dumps(settings, indent=2, sort_keys=True) + "\n"
+        ).encode("utf-8")
+        write_result = write_managed_file(
+            settings_path,
+            expected=settings_snapshot,
+            desired=desired_settings,
+            mode=existing_mode_or_default(settings_path, 0o600),
+            dir_mode=PRIVATE_DIR_MODE,
+            create_backup=not args.no_backup,
+            prepare_commit=prepare_settings_commit,
+        )
+        if write_result["status"] not in {"applied", "applied-durability-uncertain"}:
+            reason = write_result.get("reason") or "managed settings transaction was not applied"
+            raise SystemExit(f"Could not safely update {settings_path}: {reason}")
+        if write_result.get("backup_path"):
+            backup_path = Path(write_result["backup_path"])
+        rollback_id = rollback_state.get("rollback_id")
+        rollback_path = rollback_state.get("rollback_path")
+        if write_result["status"] == "applied-durability-uncertain" and write_result.get("reason"):
+            warnings.append(str(write_result["reason"]))
+        if write_result.get("residual_risk"):
+            warnings.append(str(write_result["residual_risk"]))
+        claude_settings_written = True
 
     # Build the per-adapter plan; repo-rule writes happen here when an applying
     # run (--yes) requested --with-init or project-scope --brief-mode.
@@ -2559,10 +4249,34 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--dry-run", action="store_true", help="alias for --plan")
     parser.add_argument("--verify", action="store_true", help="run a read-only setup health check; never writes or prompts")
     parser.add_argument("--json", action="store_true", help="print machine-readable result")
+    parser.add_argument(
+        "--rules-only",
+        action="store_true",
+        help="run an isolated rule-file operation without reading or changing settings/hooks",
+    )
+    parser.add_argument(
+        "--narration-mode",
+        choices=NARRATION_MODE_CHOICES,
+        default=None,
+        help="with --rules-only, add quiet Claude narration guidance or restore default behavior",
+    )
     parser.add_argument("--no-backup", action="store_true", help="do not create .bak-* before modifying existing settings")
     parser.add_argument("--no-denies", action="store_true", help="skip recommended permissions.deny rules")
     parser.add_argument("--no-statusline", action="store_true", help="skip token statusline")
     parser.add_argument("--no-bash-hook", action="store_true", help="skip Bash trim/sanitize hook")
+    reference_group = parser.add_mutually_exclusive_group()
+    reference_group.add_argument(
+        "--bash-reference-v1",
+        action="store_true",
+        help="opt in to 7-day scoped receipt references in the Bash hook; handles are provider-visible",
+    )
+    reference_group.add_argument(
+        "--no-bash-reference-v1",
+        dest="bash_reference_v1",
+        action="store_false",
+        help="disable/remove the optional Bash receipt-reference hook flag (default)",
+    )
+    parser.set_defaults(bash_reference_v1=False)
     parser.add_argument("--no-read-guard", action="store_true", help="skip large Read guard hook")
     parser.add_argument("--no-model-defaults", action="store_true", help="skip model/effort defaults")
     parser.add_argument("--no-diet-scan", action="store_true", help="skip the read-only diet scan summary after applying setup")
@@ -2613,7 +4327,7 @@ def build_parser() -> argparse.ArgumentParser:
         dest="failed_attempt_nudge",
         action="store_true",
         default=None,
-        help="enable PostToolUse Bash hook that suggests /clear when the same command fails twice in a row (recommended default)",
+        help="enable Bash terminal-event hooks that suggest /clear when the same command fails twice in a row (recommended default)",
     )
     nudge_group.add_argument(
         "--no-failed-attempt-nudge",
@@ -2628,6 +4342,14 @@ def build_parser() -> argparse.ArgumentParser:
 def main() -> int:
     parser = build_parser()
     args = parser.parse_args()
+    rules_only = validate_rules_only_args(parser, args)
+    if rules_only:
+        result = run_quiet_narration_rules(args)
+        if args.json:
+            print(json.dumps(result, indent=2, sort_keys=True))
+        else:
+            print(render_quiet_narration_text(result), end="")
+        return 0
     if args.dry_run:
         args.plan = True
     if args.verify and args.yes: