@ictechgy/context-guard 0.4.16 → 0.6.0

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

@@ -13,6 +13,7 @@ import datetime as _dt
 import hashlib
 import json
 import os
+import pwd
 import re
 import selectors
 import shlex
@@ -22,6 +23,7 @@ import stat
 import subprocess
 import sys
 import time
+import types
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
@@ -61,10 +63,21 @@ PRODUCT_OWNED_ENV_READ_DENIES = frozenset({
     "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",
@@ -99,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"),
@@ -111,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.
@@ -1464,17 +1506,65 @@ def normalize_scope(raw_scope: str | None) -> str:
     return scope
 
 
+def _user_scope_path_issue(
+    path: Path,
+    *,
+    label: str,
+    expected_directory: bool,
+    allow_missing: bool,
+) -> str | None:
+    """Return a fail-closed reason for an existing user-scope path."""
+    try:
+        metadata = os.lstat(path)
+    except FileNotFoundError:
+        return None if allow_missing else f"{label} does not exist: {path}"
+    except OSError as error:
+        return f"could not inspect {label}: {error.__class__.__name__}"
+
+    if metadata.st_uid not in {0, os.geteuid()}:
+        return f"refusing unsafe {label}: it is not owned by root or the effective user"
+    if metadata.st_mode & (stat.S_IWGRP | stat.S_IWOTH):
+        return f"refusing unsafe {label}: group/world write bits are set"
+    if expected_directory:
+        if not stat.S_ISDIR(metadata.st_mode):
+            return f"refusing unsafe {label}: it is not a directory"
+    elif not stat.S_ISREG(metadata.st_mode):
+        return f"refusing unsafe {label}: it is not a regular file"
+    return None
+
+
+def _validate_user_scope_home(home: Path) -> None:
+    issue = _user_scope_path_issue(
+        home,
+        label="resolved HOME",
+        expected_directory=True,
+        allow_missing=False,
+    )
+    if issue:
+        raise SystemExit(issue)
+
+
 def resolve_scope_root(raw_root: str | None, scope: str) -> Path:
     if scope == "project":
         return resolve_setup_root(raw_root)
     home = Path.home().expanduser().resolve()
     if home == Path(home.anchor or "/"):
         raise SystemExit("Refusing user-scope setup because HOME resolves to a filesystem root.")
-    if not home.exists() or not home.is_dir():
-        raise SystemExit(f"Refusing user-scope setup because HOME is not a directory: {home}")
+    _validate_user_scope_home(home)
     return home
 
 
+def effective_scope(raw_root: str | None, raw_scope: str | None, *, allow_home_settings: bool) -> str:
+    scope = normalize_scope(raw_scope)
+    if scope != "project" or not allow_home_settings:
+        return scope
+    project_root = resolve_setup_root(raw_root)
+    home_settings = Path.home().expanduser().resolve() / SETTINGS_REL
+    if (project_root / SETTINGS_REL).expanduser().resolve() == home_settings:
+        return "user"
+    return scope
+
+
 def explicit_agent_selection(args: argparse.Namespace) -> list[str] | None:
     values: list[str] = []
     for attr in ("agent", "only"):
@@ -1507,6 +1597,20 @@ def validate_settings_target(root: Path, settings_path: Path, *, allow_home_sett
             claude_dir.resolve().relative_to(root)
         except ValueError as exc:
             raise SystemExit(f"Claude settings directory resolves outside project root: {claude_dir}") from exc
+    if root == home_settings.parent.parent:
+        for path, label, expected_directory, allow_missing in (
+            (root, "resolved HOME", True, False),
+            (claude_dir, "existing .claude directory", True, True),
+            (settings_path, "existing settings.json", False, True),
+        ):
+            issue = _user_scope_path_issue(
+                path,
+                label=label,
+                expected_directory=expected_directory,
+                allow_missing=allow_missing,
+            )
+            if issue:
+                raise SystemExit(issue)
 
 
 def _base_open_flags() -> int:
@@ -1835,9 +1939,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"],
@@ -1974,28 +2080,440 @@ def helper_command(helper_name: str, kit_script: str, *, shell: str | None = Non
     return shlex.join(argv)
 
 
+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 _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 _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 _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 _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 _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 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]:
-    return {"type": "command", "command": helper_command(HELPER_STATUSLINE, "statusline_merged.sh", shell="bash", allow_path_fallback=allow_path_fallback)}
+    setting, _omc_included = _statusline_setting(allow_path_fallback=allow_path_fallback)
+    return setting
 
 
-def bash_hook_setting(*, allow_path_fallback: bool = False) -> dict[str, Any]:
+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": helper_command(HELPER_REWRITE_BASH, "rewrite_bash_for_token_budget.py", allow_path_fallback=allow_path_fallback)}],
+        "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": helper_command(HELPER_GUARD_READ, "guard_large_read.py", allow_path_fallback=allow_path_fallback)}],
+        "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": helper_command(HELPER_FAILED_NUDGE, "failed_attempt_nudge.py", allow_path_fallback=allow_path_fallback)}],
+        "hooks": [{"type": "command", "command": automatic_helper_command(HELPER_FAILED_NUDGE, "failed_attempt_nudge.py", allow_path_fallback=allow_path_fallback)}],
     }
 
 
@@ -2020,6 +2538,18 @@ def command_helper_basenames(command: str) -> set[str]:
     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):
@@ -2042,6 +2572,139 @@ def command_helper_basenames(command: str) -> set[str]:
     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)
@@ -2050,13 +2713,132 @@ def equivalent_helper_basenames(command: str) -> set[str]:
     return equivalents
 
 
-def command_matches_existing_or_equivalent(existing: str, desired: str) -> bool:
+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
+    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
-    return bool(command_helper_basenames(existing) & desired_helpers)
+    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]:
@@ -2250,14 +3032,21 @@ def doctor_check(
     return check
 
 
-def _setup_command(args: argparse.Namespace, *, apply: bool, root: Path | None = None) -> str:
-    parts = ["context-guard", "setup", "--scope", normalize_scope(getattr(args, "scope", "project"))]
-    if root is not None and normalize_scope(getattr(args, "scope", "project")) == "project":
+def _setup_command(
+    args: argparse.Namespace,
+    *,
+    apply: bool,
+    root: Path | None = None,
+    scope: str | None = None,
+) -> str:
+    scope = scope or normalize_scope(getattr(args, "scope", "project"))
+    parts = ["context-guard", "setup", "--scope", scope]
+    if root is not None and scope == "project":
         parts.extend(["--root", str(root)])
     selected = explicit_agent_selection(args)
     if selected:
         parts.extend(["--agent", ",".join(selected)])
-    elif normalize_scope(getattr(args, "scope", "project")) == "user":
+    elif scope == "user":
         parts.extend(["--agent", "claude"])
     if getattr(args, "allow_path_helper_fallback", False):
         parts.append("--allow-path-helper-fallback")
@@ -2348,7 +3137,11 @@ def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
     writing settings, writing rule files, or creating rollback records.
     """
     require_no_follow_file_ops_supported()
-    scope = normalize_scope(getattr(args, "scope", "project"))
+    scope = effective_scope(
+        args.root,
+        getattr(args, "scope", "project"),
+        allow_home_settings=bool(getattr(args, "allow_home_settings", False)),
+    )
     root = resolve_scope_root(args.root, scope)
     settings_path = root / SETTINGS_REL
     helper_check = _helper_availability_check(include_diet=not getattr(args, "no_diet_scan", False), allow_path_fallback=bool(getattr(args, "allow_path_helper_fallback", False)))
@@ -2440,7 +3233,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(
@@ -2449,7 +3263,7 @@ def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
             "medium",
             "ContextGuard setup is not fully applied for the requested selections.",
             detail={"planned_action_count": len(actions), "planned_actions": actions},
-            next_action=_setup_command(args, apply=False, root=root),
+            next_action=_setup_command(args, apply=False, root=root, scope=scope),
         ))
     else:
         checks.append(doctor_check(
@@ -2484,7 +3298,7 @@ def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
             "medium",
             "Some requested adapters still have planned or unsupported setup actions.",
             detail={"adapters": adapter_warnings},
-            next_action=_setup_command(args, apply=False, root=root),
+            next_action=_setup_command(args, apply=False, root=root, scope=scope),
         ))
     else:
         checks.append(doctor_check(
@@ -2538,9 +3352,9 @@ def run_doctor(args: argparse.Namespace) -> dict[str, Any]:
                     detail=diet_scan,
                 ))
 
-    recommended = [_setup_command(args, apply=False, root=root)]
+    recommended = [_setup_command(args, apply=False, root=root, scope=scope)]
     if changed or adapter_warnings:
-        recommended.append(_setup_command(args, apply=True, root=root))
+        recommended.append(_setup_command(args, apply=True, root=root, scope=scope))
     return {
         "schema_version": "contextguard.doctor.v1",
         "status": _doctor_status(checks),
@@ -2596,12 +3410,29 @@ 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,
@@ -2609,9 +3440,16 @@ def apply_choices(settings: dict[str, Any], choices: Choices, *, allow_path_fall
             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"]
@@ -3004,6 +3842,10 @@ 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(
@@ -3019,6 +3861,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=(
@@ -3280,7 +4123,11 @@ def render_quiet_narration_text(result: dict[str, Any]) -> str:
 
 def run(args: argparse.Namespace) -> SetupResult:
     require_no_follow_file_ops_supported()
-    scope = normalize_scope(getattr(args, "scope", "project"))
+    scope = effective_scope(
+        args.root,
+        getattr(args, "scope", "project"),
+        allow_home_settings=bool(getattr(args, "allow_home_settings", False)),
+    )
     root = resolve_scope_root(args.root, scope)
     settings_path = root / SETTINGS_REL
     warnings: list[str] = []
@@ -3327,7 +4174,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)
@@ -3481,6 +4341,19 @@ def build_parser() -> argparse.ArgumentParser:
     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")