@ictechgy/context-guard 0.4.15 → 0.4.16

package/plugins/context-guard/bin/context-guard-guard-read

@@ -8,6 +8,7 @@ remain supported for existing project settings.
 """
 from __future__ import annotations
 
+import copy
 import errno
 import hashlib
 import importlib.util
@@ -18,8 +19,9 @@ import secrets
 import shlex
 import stat
 import sys
+import time
 from pathlib import Path
-from typing import Any
+from typing import Any, NamedTuple
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 
@@ -52,13 +54,25 @@ OUTLINE_MAX_BYTES = 200_000
 OUTLINE_MAX_ITEMS = 12
 READ_GUARD_STATE_DIR = Path(".context-guard")
 READ_GUARD_STATE_FILE = "read-guard-cache.json"
-READ_GUARD_STATE_MAX_ITEMS = 20
+READ_GUARD_STATE_MAX_ITEMS = 128
 GUARD_ENV = "CONTEXT_GUARD_READ_GUARD"
 LEGACY_GUARD_ENV = "CLAUDE_TOKEN_READ_GUARD"
 MAX_BYTES_ENV = "CONTEXT_GUARD_READ_GUARD_MAX_BYTES"
 LEGACY_MAX_BYTES_ENV = "CLAUDE_TOKEN_READ_GUARD_MAX_BYTES"
 MAX_LINE_RANGE_ENV = "CONTEXT_GUARD_READ_GUARD_MAX_LINES"
 LEGACY_MAX_LINE_RANGE_ENV = "CLAUDE_TOKEN_READ_GUARD_MAX_LINES"
+READ_PROOF_BYTES_ENV = "CONTEXT_GUARD_READ_GUARD_PROOF_BYTES"
+LEGACY_READ_PROOF_BYTES_ENV = "CLAUDE_TOKEN_READ_GUARD_PROOF_BYTES"
+DEFAULT_READ_PROOF_BYTES = 8 * 1024 * 1024
+MIN_READ_PROOF_BYTES = 64 * 1024
+MAX_READ_PROOF_BYTES = 64 * 1024 * 1024
+READ_PROOF_CHUNK_BYTES = 64 * 1024
+MAX_READ_RANGE_INTEGER = (1 << 63) - 1
+ALLOWED_ENV_TEMPLATE_BASENAMES = frozenset({
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+})
 PATH_LABEL_MAX_CHARS = 160
 ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
     "tmp": Path("/private/tmp"),
@@ -110,6 +124,16 @@ def max_line_range() -> int:
     )
 
 
+def read_proof_bytes() -> int:
+    return bounded_env_int(
+        READ_PROOF_BYTES_ENV,
+        LEGACY_READ_PROOF_BYTES_ENV,
+        DEFAULT_READ_PROOF_BYTES,
+        MIN_READ_PROOF_BYTES,
+        MAX_READ_PROOF_BYTES,
+    )
+
+
 def tool_input(payload: dict[str, Any]) -> dict[str, Any]:
     value = payload.get("tool_input") or payload.get("toolInput") or {}
     return value if isinstance(value, dict) else {}
@@ -145,25 +169,48 @@ def anonymized_path_label(path: Path) -> str:
     return f"redacted-path#path:{digest}"
 
 
-def bounded_line_range_requested(payload: dict[str, Any]) -> bool:
-    data = tool_input(payload)
-    raw_limit = data.get("limit")
-    if raw_limit is None:
-        return False
+def strict_integer(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if not isinstance(value, str):
+        return None
+    normalized = value.strip()
+    if not re.fullmatch(r"[+-]?[0-9]+", normalized):
+        return None
     try:
-        limit = int(raw_limit)
-    except (TypeError, ValueError):
-        return False
+        return int(normalized)
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def large_read_range(payload: dict[str, Any]) -> tuple[int, int] | None:
+    data = tool_input(payload)
+    limit = strict_integer(data.get("limit"))
+    if limit is None:
+        return None
     if limit <= 0 or limit > max_line_range():
-        return False
-    raw_offset = data.get("offset")
-    if raw_offset is not None:
-        try:
-            if int(raw_offset) < 0:
-                return False
-        except (TypeError, ValueError):
-            return False
-    return True
+        return None
+    raw_offset = data.get("offset", 0)
+    offset = strict_integer(raw_offset)
+    if offset is None or offset < 0 or offset > MAX_READ_RANGE_INTEGER:
+        return None
+    if limit > MAX_READ_RANGE_INTEGER - offset:
+        return None
+    return offset, limit
+
+
+def bounded_line_range_requested(payload: dict[str, Any]) -> bool:
+    return large_read_range(payload) is not None
+
+
+def read_env_file_denied(path: Path) -> bool:
+    basename = path.name
+    return (
+        basename.casefold().startswith(".env")
+        and basename not in ALLOWED_ENV_TEMPLATE_BASENAMES
+    )
 
 
 def safe_label(path: Path, root: Path) -> str:
@@ -362,6 +409,114 @@ def regular_file_size_no_symlink(path: Path) -> int:
         os.close(fd)
 
 
+class ReadRangeProof(NamedTuple):
+    outcome: str
+    charged_bytes: int
+    scanned_bytes: int
+
+
+def stat_identity(stat_result: os.stat_result) -> tuple[int, int, int, int]:
+    mtime_ns = getattr(
+        stat_result,
+        "st_mtime_ns",
+        int(stat_result.st_mtime * 1_000_000_000),
+    )
+    return (
+        stat_result.st_dev,
+        stat_result.st_ino,
+        stat_result.st_size,
+        mtime_ns,
+    )
+
+
+def prove_raw_read_range(
+    fd: int,
+    *,
+    file_size: int,
+    offset: int,
+    limit: int,
+    content_budget: int,
+    proof_budget: int,
+) -> ReadRangeProof:
+    """Prove a zero-based logical-line range from raw bytes on one open fd."""
+    if (
+        file_size < 0
+        or offset < 0
+        or limit <= 0
+        or content_budget < 0
+        or proof_budget <= 0
+        or offset > MAX_READ_RANGE_INTEGER
+        or limit > MAX_READ_RANGE_INTEGER - offset
+    ):
+        raise ValueError("invalid raw Read proof parameters")
+
+    selected_end = offset + limit
+    line_index = 0
+    charged_bytes = 0
+    scanned_bytes = 0
+    os.lseek(fd, 0, os.SEEK_SET)
+
+    while scanned_bytes < file_size and scanned_bytes < proof_budget:
+        remaining = min(
+            READ_PROOF_CHUNK_BYTES,
+            file_size - scanned_bytes,
+            proof_budget - scanned_bytes,
+        )
+        chunk = os.read(fd, remaining)
+        if not chunk:
+            return ReadRangeProof("file_changed_during_proof", charged_bytes, scanned_bytes)
+        for byte in chunk:
+            scanned_bytes += 1
+            if byte == 0x0A:
+                line_index += 1
+                if line_index >= selected_end:
+                    return ReadRangeProof("allowed", charged_bytes, scanned_bytes)
+                continue
+            if offset <= line_index < selected_end:
+                charged_bytes += 1
+                if charged_bytes > content_budget:
+                    return ReadRangeProof("content_budget_exceeded", charged_bytes, scanned_bytes)
+
+    if scanned_bytes >= file_size:
+        return ReadRangeProof("allowed", charged_bytes, scanned_bytes)
+    return ReadRangeProof("proof_budget_exhausted", charged_bytes, scanned_bytes)
+
+
+def raw_read_range_outcome(
+    fd: int,
+    initial_stat: os.stat_result,
+    *,
+    size: int,
+    offset: int,
+    limit: int,
+    content_limit: int,
+) -> str:
+    """지정된 offset/limit로 raw-byte 증명을 수행하고 동일 fd의 정체성 변화까지 확인한다.
+
+    peek/commit 분리 설계의 핵심: 밸브 판정과 증명이 fd 보유 구간 안에서만 일어나며
+    별도로 재개방하지 않으므로 새 TOCTOU 창을 만들지 않는다.
+    """
+    try:
+        proof = prove_raw_read_range(
+            fd,
+            file_size=size,
+            offset=offset,
+            limit=limit,
+            content_budget=content_limit,
+            proof_budget=read_proof_bytes(),
+        )
+        outcome = proof.outcome
+    except (OSError, ValueError):
+        outcome = "read_proof_failed"
+    try:
+        final_stat = os.fstat(fd)
+    except OSError:
+        return "file_changed_during_proof"
+    if stat_identity(initial_stat) != stat_identity(final_stat):
+        return "file_changed_during_proof"
+    return outcome
+
+
 def find_read_symbol_command() -> str:
     script_dir = Path(__file__).resolve().parent
     if (script_dir / "context-guard-read-symbol").exists():
@@ -473,10 +628,19 @@ def line_estimate(prefix: str, size: int, truncated: bool) -> str:
     return f"~{estimated} (estimated from first {lines})"
 
 
-def progressive_read_ladder(path: Path, label: str, size: int, limit: int, read_symbol: str) -> str:
+def progressive_read_ladder(
+    path: Path,
+    label: str,
+    size: int,
+    limit: int,
+    read_symbol: str,
+    *,
+    command_path: str | None = None,
+) -> str:
     prefix, prefix_truncated = read_prefix_for_outline(path)
     items = outline_items(path, prefix)
-    rg_cmd, symbol_cmd = suggested_commands(label, read_symbol)
+    actionable_path = command_path if command_path is not None else label
+    rg_cmd, symbol_cmd = suggested_commands(actionable_path, read_symbol)
     range_limit = min(max_line_range(), 120)
     parts = [
         f"[context-guard-kit] Large Read blocked for {label} ({size} bytes > {limit} byte guard).",
@@ -485,7 +649,7 @@ def progressive_read_ladder(path: Path, label: str, size: int, limit: int, read_
     ]
     if items:
         first_name = items[0].split(" ", 3)[-1].split(" ", 1)[-1]
-        read_parts = shlex.split(read_symbol) + [label, first_name]
+        read_parts = shlex.split(read_symbol) + [actionable_path, first_name]
         parts.append(f"2) Read a symbol slice: `{shlex.join(read_parts)}` (or `{symbol_cmd}`)")
     else:
         parts.append(f"2) Read a symbol slice when you know the name: `{symbol_cmd}`")
@@ -501,12 +665,111 @@ def progressive_read_ladder(path: Path, label: str, size: int, limit: int, read_
     return " ".join(parts)
 
 
-def read_guard_fingerprint(path: Path, label: str, size: int) -> str:
+def project_relative_path(path: Path, root: Path) -> str | None:
     try:
-        stat_result = path.stat()
-        mtime = getattr(stat_result, "st_mtime_ns", int(stat_result.st_mtime * 1_000_000_000))
-    except OSError:
+        normalized_path = Path(os.path.abspath(os.fspath(path)))
+        normalized_root = Path(os.path.abspath(os.fspath(root)))
+        return normalized_path.relative_to(normalized_root).as_posix()
+    except (OSError, ValueError):
+        return None
+
+
+def project_relative_command_path(path: Path, root: Path) -> str | None:
+    relative = project_relative_path(path, root)
+    if relative is None:
+        return None
+    if (
+        not relative
+        or len(relative) > PATH_LABEL_MAX_CHARS
+        or CONTROL_CHAR_RE.search(relative)
+        or hook_label_has_sensitive_evidence(relative)
+    ):
+        return None
+    return relative
+
+
+def read_proof_denial_reason(
+    outcome: str,
+    *,
+    path: Path,
+    root: Path,
+    size: int,
+    content_limit: int,
+    read_symbol: str,
+) -> str:
+    relative_project_path = project_relative_path(path, root)
+    relative_path = project_relative_command_path(path, root)
+    if outcome == "file_changed_during_proof":
+        if relative_project_path is None:
+            target = "an out-of-project file"
+        elif relative_path is None:
+            target = safe_label(path, root)
+        else:
+            target = f"project file `{shlex.quote(relative_path)}`"
+        return (
+            f"[context-guard-kit] Read blocked for {target}: file_changed_during_proof. "
+            "The same open file changed identity, size, or modification time during the bounded proof. "
+            "Stabilize the file and retry with a smaller positive limit. A later Read uses a separate open, "
+            "so replacement after this hook returns remains a TOCTOU limitation."
+        )
+
+    outcome_detail = {
+        "invalid_read_range": (
+            "Large files require a positive integer limit within the configured maximum and a "
+            "zero-based, nonnegative, nonoverflowing integer offset."
+        ),
+        "proof_budget_exhausted": (
+            "The guard could not prove the requested start/end boundary or EOF within the raw-byte proof budget."
+        ),
+        "content_budget_exceeded": (
+            "The selected logical-line content exceeds the byte guard; LF terminators are not charged, "
+            "but CR and EOF-final content bytes are."
+        ),
+    }.get(outcome, "The bounded raw-byte Read proof could not safely allow this request.")
+
+    if relative_project_path is None:
+        return (
+            f"[context-guard-kit] Large Read blocked for an out-of-project file "
+            f"({size} bytes > {content_limit} byte guard): {outcome}. {outcome_detail} "
+            "Use a smaller positive limit and lower zero-based offset, or first perform an explicitly "
+            "user-authorized path-visible operation. No executable path suggestion is emitted for path privacy."
+        )
+    if relative_path is None:
+        return (
+            f"[context-guard-kit] Large Read blocked for {safe_label(path, root)} "
+            f"({size} bytes > {content_limit} byte guard): {outcome}. {outcome_detail} "
+            "Use a smaller positive limit and lower zero-based offset. No executable path suggestion is emitted "
+            "because this project-relative path contains privacy-sensitive or non-command-safe bytes."
+        )
+
+    label = safe_label(path, root)
+    ladder = progressive_read_ladder(
+        path,
+        label,
+        size,
+        content_limit,
+        read_symbol,
+        command_path=relative_path,
+    )
+    return f"{ladder} Read proof outcome={outcome}. {outcome_detail}"
+
+
+def read_guard_fingerprint(
+    path: Path,
+    label: str,
+    size: int,
+    *,
+    stat_result: os.stat_result | None = None,
+) -> str:
+    if stat_result is None:
+        try:
+            stat_result = path.stat()
+        except OSError:
+            stat_result = None
+    if stat_result is None:
         mtime = 0
+    else:
+        mtime = getattr(stat_result, "st_mtime_ns", int(stat_result.st_mtime * 1_000_000_000))
     basis = f"{label}\0{size}\0{mtime}"
     return hashlib.sha256(basis.encode("utf-8", errors="replace")).hexdigest()[:16]
 
@@ -568,26 +831,66 @@ def save_read_guard_state(root: Path, state: dict[str, Any]) -> None:
         return
 
 
-def record_read_guard_attempt(root: Path, fp: str) -> int:
+def default_read_guard_entry() -> dict[str, Any]:
+    """캐시에 아직 없거나 손상된 지문에 사용할 기본 시도 엔트리."""
+    return {"count": 0, "valve_used": False, "first_seen": 0, "last_seen": 0}
+
+
+def normalize_read_guard_entry(entry: Any) -> dict[str, Any]:
+    """레거시 `{"count": N}` 및 손상된 엔트리를 신규 스키마로 하위 호환 정규화한다."""
+    normalized = default_read_guard_entry()
+    if not isinstance(entry, dict):
+        return normalized
+    normalized["count"] = bounded_int(entry.get("count", 0), 0, 0, 1_000_000)
+    normalized["valve_used"] = bool(entry.get("valve_used", False))
+    normalized["first_seen"] = bounded_int(entry.get("first_seen", 0), 0, 0, MAX_READ_RANGE_INTEGER)
+    normalized["last_seen"] = bounded_int(entry.get("last_seen", 0), 0, 0, MAX_READ_RANGE_INTEGER)
+    return normalized
+
+
+def peek_read_guard_attempt(root: Path, fp: str) -> dict[str, Any]:
+    """카운터를 증가시키지 않고 현재 지문의 시도 엔트리를 읽는다(밸브 판정 전용).
+
+    밸브 발화 여부는 대상 fd 보유 구간 안에서 결정해야 하므로, 영속화(commit)와
+    분리된 읽기 전용 조회로 둔다. 대상 파일의 fd는 건드리지 않는다.
+    """
+    state = load_read_guard_state(root)
+    attempts = state.get("attempts")
+    if not isinstance(attempts, dict):
+        return default_read_guard_entry()
+    return normalize_read_guard_entry(attempts.get(fp))
+
+
+def record_read_guard_attempt(root: Path, fp: str, *, valve_fired: bool = False) -> int:
+    """시도 횟수를 1 증가시키고 병합 방식으로 영속화한다(commit 단계, fd 미보유 구간).
+
+    기존 엔트리를 통째로 덮어쓰지 않고 필드를 병합해 valve_used/first_seen/last_seen을
+    보존한다. pop 후 재삽입 순서를 유지해 초과분 축출을 LRU 유사하게 만든다.
+    valve_used 등 전체 엔트리 조회가 필요하면 별도로 peek_read_guard_attempt를 쓴다
+    (이 함수의 반환값은 호출부가 실제로 쓰는 count만 담는다).
+    """
     state = load_read_guard_state(root)
     attempts = state.get("attempts")
     if not isinstance(attempts, dict):
         attempts = {}
-    entry = attempts.get(fp)
-    if not isinstance(entry, dict):
-        entry = {"count": 0}
-    count = bounded_int(entry.get("count", 0), 0, 0, 1_000_000) + 1
+    entry = normalize_read_guard_entry(attempts.get(fp))
+    now = int(time.time())
+    entry["count"] += 1
+    entry["valve_used"] = entry["valve_used"] or valve_fired
+    entry["first_seen"] = entry["first_seen"] or now
+    entry["last_seen"] = now
     attempts.pop(fp, None)
-    attempts[fp] = {"count": count}
+    attempts[fp] = entry
     if len(attempts) > READ_GUARD_STATE_MAX_ITEMS:
         for key in list(attempts)[: len(attempts) - READ_GUARD_STATE_MAX_ITEMS]:
             attempts.pop(key, None)
     state["attempts"] = attempts
     save_read_guard_state(root, state)
-    return count
+    return entry["count"]
 
 
 def repeated_read_hint(count: int) -> str:
+    """1~2회차 사다리 거부에 덧붙이는 반복 신호 문구(3회차부터는 단축 메시지를 대신 쓴다)."""
     if count < 2:
         return ""
     return (
@@ -596,6 +899,30 @@ def repeated_read_hint(count: int) -> str:
     )
 
 
+def valve_exhausted_reason(count: int) -> str:
+    """지문이 과거에 실제로 밸브를 1회 발화(valve_used=True)한 뒤 다시 차단됐을 때 쓰는
+    200바이트 미만 단축 메시지. "발화했다가 소진됨"을 뜻하므로 발화한 적이 없는
+    지문에는 절대 쓰지 않는다 — 그 경우는 valve_budget_exceeded_reason을 쓴다.
+    """
+    return (
+        f"[context-guard-kit] Read blocked ({count}x, escape valve exhausted). "
+        "Use a smaller offset/limit range for this file."
+    )
+
+
+def valve_budget_exceeded_reason(count: int, content_limit: int) -> str:
+    """좁힌 기본 범위(offset=0, limit=max_line_range())조차 예산을 넘어 밸브가 구조적으로
+    발화할 수 없는 지문(minified/JSON/CSV/로그처럼 줄이 긴 파일)에 쓰는 200바이트 미만
+    단축 메시지. "탈진"이라 말하지 않는다 — 애초에 켜진 적이 없기 때문이다. 실제 예산
+    수치를 실어 에이전트가 스스로 유효한 offset/limit을 계산할 수 있게 한다.
+    """
+    return (
+        f"[context-guard-kit] Large Read blocked ({count}x). Narrowed {max_line_range()}-line "
+        f"range still exceeds the {content_limit:,}-byte guard; supply an explicit offset/limit "
+        "under it."
+    )
+
+
 def deny_response(reason: str) -> dict[str, Any]:
     return {
         "hookSpecificOutput": {
@@ -606,6 +933,18 @@ def deny_response(reason: str) -> dict[str, Any]:
     }
 
 
+def valve_updated_input_response(payload: dict[str, Any], offer: tuple[int, int]) -> dict[str, Any]:
+    """3회차 밸브가 발화했을 때 offset/limit을 주입한 updatedInput 훅 응답을 만든다."""
+    updated_input = copy.deepcopy(tool_input(payload))
+    updated_input["offset"], updated_input["limit"] = offer
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "updatedInput": updated_input,
+        }
+    }
+
+
 def main() -> int:
     if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
         print("ContextGuard helper: context-guard-guard-read")
@@ -634,11 +973,21 @@ def main() -> int:
         print("{}")
         return 0
     root = Path.cwd().resolve()
-    path = Path(raw_path).expanduser()
-    if not path.is_absolute():
-        path = root / path
-    path = normalize_allowed_first_absolute_symlink(path)
-    if has_symlink_component(path):
+    try:
+        path = Path(raw_path).expanduser()
+        if not path.is_absolute():
+            path = root / path
+        path = Path(os.path.abspath(os.fspath(path)))
+        path = normalize_allowed_first_absolute_symlink(path)
+        traverses_symlink = has_symlink_component(path)
+    except (OSError, RuntimeError, ValueError):
+        reason = (
+            "[context-guard-kit] Read blocked because the requested file path could not be normalized safely. "
+            "Retry with a valid, explicit file path."
+        )
+        print(json.dumps(deny_response(reason), ensure_ascii=False))
+        return 0
+    if traverses_symlink:
         label = safe_label(path, root)
         reason = (
             f"[context-guard-kit] Read blocked for {label}: requested path traverses a symlink. "
@@ -646,10 +995,64 @@ def main() -> int:
         )
         print(json.dumps(deny_response(reason), ensure_ascii=False))
         return 0
+    if read_env_file_denied(path):
+        reason = (
+            "[context-guard-kit] Read blocked by the Read-only environment-file policy: the normalized basename "
+            "begins with .env and is not exactly .env.example, .env.sample, or .env.template. "
+            "This hook protects Claude Read only; Glob name listings, Grep, and Bash/process access are out of scope."
+        )
+        print(json.dumps(deny_response(reason), ensure_ascii=False))
+        return 0
+    content_limit = max_bytes()
+    size = 0
+    initial_stat: os.stat_result | None = None
+    outcome = "invalid_read_range"
+    fingerprint = ""
+    valve_offer: tuple[int, int] | None = None
+    fd = -1
     try:
-        size = regular_file_size_no_symlink(path)
-    except OSError as exc:
-        if exc.errno == errno.ELOOP:
+        fd = open_regular_no_symlink(path)
+        initial_stat = os.fstat(fd)
+        size = initial_stat.st_size
+        if size <= content_limit:
+            print("{}")
+            return 0
+
+        # peek: fd 보유 구간 안에서 밸브 판정에 쓸 이전 시도 횟수를 읽는다(쓰기 없음).
+        fingerprint = read_guard_fingerprint(path, safe_label(path, root), size, stat_result=initial_stat)
+        attempt_peek = peek_read_guard_attempt(root, fingerprint)
+
+        requested_range = large_read_range(payload)
+        if requested_range is not None:
+            outcome = raw_read_range_outcome(
+                fd,
+                initial_stat,
+                size=size,
+                offset=requested_range[0],
+                limit=requested_range[1],
+                content_limit=content_limit,
+            )
+
+        if (
+            outcome not in ("allowed", "file_changed_during_proof")
+            and attempt_peek["count"] + 1 == 3
+            and not attempt_peek["valve_used"]
+        ):
+            candidate = (0, max_line_range())
+            candidate_outcome = raw_read_range_outcome(
+                fd,
+                initial_stat,
+                size=size,
+                offset=candidate[0],
+                limit=candidate[1],
+                content_limit=content_limit,
+            )
+            if candidate_outcome == "allowed":
+                outcome = "allowed"
+                valve_offer = candidate
+    except (OSError, ValueError) as exc:
+        error_number = getattr(exc, "errno", None)
+        if error_number == errno.ELOOP:
             label = safe_label(path, root)
             reason = (
                 f"[context-guard-kit] Read blocked for {label}: requested path traverses a symlink. "
@@ -657,34 +1060,66 @@ def main() -> int:
             )
             print(json.dumps(deny_response(reason), ensure_ascii=False))
             return 0
-        if exc.errno in {errno.EINVAL, errno.ENOTDIR, errno.ENOENT}:
+        if error_number == errno.ENOENT:
             print("{}")
             return 0
         label = safe_label(path, root)
-        detail = compact_hook_text(exc.strerror or exc.__class__.__name__, 80)
+        detail = compact_hook_text(getattr(exc, "strerror", "") or exc.__class__.__name__, 80)
         print(f"context-guard-guard-read: could not safely inspect requested file: {detail}", file=sys.stderr)
-        reason = (
-            f"[context-guard-kit] Read blocked for {label}: the guard could not safely inspect the file "
-            f"({detail}). Use a bounded line range or verify the path locally first."
-        )
+        if error_number in {errno.EINVAL, errno.ENOTDIR, errno.EISDIR}:
+            reason = (
+                f"[context-guard-kit] Read blocked for {label}: requested path is not a regular file. "
+                "Use a real, non-symlink file path before reading."
+            )
+        else:
+            reason = (
+                f"[context-guard-kit] Read blocked for {label}: the guard could not safely inspect the file "
+                f"({detail}). Use a bounded line range or verify the path locally first."
+            )
         print(json.dumps(deny_response(reason), ensure_ascii=False))
         return 0
+    finally:
+        if fd != -1:
+            os.close(fd)
 
-    limit = max_bytes()
-    if size <= limit:
-        print("{}")
+    if outcome == "allowed" and valve_offer is not None:
+        # commit: fd 종료 이후 밸브 발화를 지문에 1회로 기록한다(FIFO/LRU 유사 축출 유지).
+        try:
+            record_read_guard_attempt(root, fingerprint, valve_fired=True)
+        except Exception:
+            pass
+        print(json.dumps(valve_updated_input_response(payload, valve_offer), ensure_ascii=False))
         return 0
-    if bounded_line_range_requested(payload):
+
+    if outcome == "allowed":
         print("{}")
         return 0
 
-    label = safe_label(path, root)
-    read_symbol = find_read_symbol_command()
     try:
-        attempt_count = record_read_guard_attempt(root, read_guard_fingerprint(path, label, size))
+        attempt_count = record_read_guard_attempt(root, fingerprint, valve_fired=False)
     except Exception:
         attempt_count = 1
-    reason = progressive_read_ladder(path, label, size, limit, read_symbol) + repeated_read_hint(attempt_count)
+
+    # 3단 분기. 1) count<3: 아직 자기 교정 여지가 있으므로 전체 사다리를 준다.
+    # 2) count>=3, valve_used=False: 밸브가 3회차에 시도됐고(구성상 이 카운트에
+    #    도달하려면 반드시 시도됐다) 구조적으로 발화할 수 없었던 지문 — "탈진"이
+    #    아니라 "애초에 켤 수 없다"이므로 실제 예산 수치가 담긴 실행 가능한 단축
+    #    메시지를 쓴다. 3) valve_used=True: 과거에 실제로 발화했던 지문 — 기존
+    #    "탈진" 단축 메시지.
+    if attempt_peek["valve_used"]:
+        reason = valve_exhausted_reason(attempt_count)
+    elif attempt_count >= 3:
+        reason = valve_budget_exceeded_reason(attempt_count, content_limit)
+    else:
+        read_symbol = find_read_symbol_command()
+        reason = read_proof_denial_reason(
+            outcome,
+            path=path,
+            root=root,
+            size=size,
+            content_limit=content_limit,
+            read_symbol=read_symbol,
+        ) + repeated_read_hint(attempt_count)
     print(json.dumps(deny_response(reason), ensure_ascii=False))
     return 0