@ictechgy/context-guard 0.4.15 → 0.4.16

package/plugins/context-guard/bin/context-guard-statusline

@@ -11,6 +11,29 @@ if ! command -v python3 >/dev/null 2>&1; then
   exit 0
 fi
 
+statusline_path=$0
+for _context_guard_symlink_hop in {1..32}; do
+  [[ -L "$statusline_path" ]] || break
+  statusline_link_dir=$(CDPATH= cd -P -- "$(dirname -- "$statusline_path")" && pwd) || break
+  statusline_link_target=$(readlink "$statusline_path" 2>/dev/null) || break
+  if [[ "$statusline_link_target" = /* ]]; then
+    statusline_path=$statusline_link_target
+  else
+    statusline_path=$statusline_link_dir/$statusline_link_target
+  fi
+done
+statusline_dir=$(CDPATH= cd -P -- "$(dirname -- "$statusline_path")" && pwd)
+usage_reducer_file=''
+for candidate in \
+  "$statusline_dir/transcript_usage_reducer.py" \
+  "$statusline_dir/../lib/transcript_usage_reducer.py"; do
+  if [[ -f "$candidate" && ! -L "$candidate" ]]; then
+    usage_reducer_file=$(CDPATH= cd -P -- "$(dirname -- "$candidate")" && printf '%s/%s\n' "$PWD" "$(basename -- "$candidate")")
+    break
+  fi
+done
+export CONTEXT_GUARD_USAGE_REDUCER_FILE="$usage_reducer_file"
+
 read -r -d '' CONTEXT_GUARD_STATUSLINE_PY <<'PYEOF' || true
 from __future__ import annotations
 
@@ -22,14 +45,18 @@ import re
 import stat
 import sys
 import time
+import types
 from typing import Any
 
 TAIL_BYTES = 1024 * 1024
 MAX_RECORDS = 300
-CACHE_SCHEMA_VERSION = 1
+CACHE_SCHEMA_VERSION = 2
+CACHE_REDUCER_SCHEMA = "usage-reducer-v2"
+USAGE_METRIC_LABEL = "usage_tail_v2"
 DEFAULT_CACHE_TTL_SECONDS = 2.0
 MAX_CACHE_TTL_SECONDS = 30.0
 MAX_CACHE_BYTES = 4096
+MAX_REDUCER_BYTES = 512 * 1024
 METRIC_RE = re.compile(r"^\d+(?:\.\d)?$")
 SECRET_RE = re.compile(
     r"(gh[pousr]_|github_pat_|glpat-|xox[abprs]-|AKIA|ASIA|sk-|npm_|AIza|Bearer\s|Basic\s)",
@@ -39,6 +66,44 @@ OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
 CSI_RE = re.compile(r"\x1b[@-_][0-?]*[ -/]*[@-~]")
 CONTROL_RE = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]")
 
+def _load_usage_reducer(path: str) -> tuple[str, Any | None]:
+    if not path or not os.path.isabs(path):
+        return CACHE_REDUCER_SCHEMA, None
+    fd = -1
+    try:
+        flags = os.O_RDONLY
+        if hasattr(os, "O_CLOEXEC"):
+            flags |= os.O_CLOEXEC
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        fd = os.open(path, flags)
+        opened = os.fstat(fd)
+        if not stat.S_ISREG(opened.st_mode) or opened.st_size > MAX_REDUCER_BYTES:
+            return CACHE_REDUCER_SCHEMA, None
+        source = os.read(fd, opened.st_size + 1)
+        if len(source) != opened.st_size:
+            return CACHE_REDUCER_SCHEMA, None
+        module_name = "_context_guard_statusline_usage_reducer"
+        module = types.ModuleType(module_name)
+        module.__file__ = path
+        sys.modules[module_name] = module
+        exec(compile(source, path, "exec"), module.__dict__)
+        schema = getattr(module, "REDUCER_SCHEMA", "")
+        reducer = getattr(module, "UsageReducer", None)
+        if not isinstance(schema, str) or reducer is None:
+            return CACHE_REDUCER_SCHEMA, None
+        return schema, reducer
+    except Exception:
+        return CACHE_REDUCER_SCHEMA, None
+    finally:
+        if fd >= 0:
+            os.close(fd)
+
+
+REDUCER_SCHEMA, UsageReducer = _load_usage_reducer(
+    os.environ.get("CONTEXT_GUARD_USAGE_REDUCER_FILE", "")
+)
+
 
 def _bounded_int_env(primary: str, legacy: str, default: int, *, lower: int, upper: int) -> int:
     raw = os.environ.get(primary, os.environ.get(legacy, str(default)))
@@ -159,31 +224,6 @@ def git_head_branch(current: str) -> str | None:
     return None
 
 
-def _int_or_zero(value: Any) -> int:
-    """Coerce transcript usage token values. bool is an int subclass, so block it."""
-    if isinstance(value, bool):
-        return 0
-    if isinstance(value, int):
-        return max(0, value)
-    return 0
-
-
-def _extract_usage(record: Any) -> dict[str, Any] | None:
-    """Extract one known transcript usage object without recursively double-counting copies."""
-    if not isinstance(record, dict):
-        return None
-    for path_keys in (("usage",), ("message", "usage"), ("response", "usage")):
-        cur: Any = record
-        for key in path_keys:
-            if not isinstance(cur, dict):
-                cur = None
-                break
-            cur = cur.get(key)
-        if isinstance(cur, dict):
-            return cur
-    return None
-
-
 def _open_regular_transcript(path: str) -> tuple[int, os.stat_result] | None:
     flags = os.O_RDONLY
     if hasattr(os, "O_CLOEXEC"):
@@ -278,6 +318,7 @@ def _identity(path: str, st: os.stat_result) -> dict[str, int | str]:
     absolute = os.path.abspath(path)
     path_hash = hashlib.sha256(os.fsencode(absolute)).hexdigest()
     return {
+        "reducer_schema": CACHE_REDUCER_SCHEMA,
         "path_hash": path_hash,
         "size": int(st.st_size),
         "mtime_ns": int(getattr(st, "st_mtime_ns", int(st.st_mtime * 1_000_000_000))),
@@ -326,7 +367,7 @@ def _validated_metric(value: Any, *, minimum: float, maximum: float) -> str | No
     return value
 
 
-def _metric_parts(cache_pct: Any, reuse_x: Any) -> str | None:
+def _metric_parts(cache_pct: Any, reuse_x: Any, window_partial: Any) -> str | None:
     cache_pct = _validated_metric(cache_pct, minimum=0.0, maximum=100.0)
     if cache_pct is None:
         return None
@@ -334,7 +375,13 @@ def _metric_parts(cache_pct: Any, reuse_x: Any) -> str | None:
         reuse_x = _validated_metric(reuse_x, minimum=0.0, maximum=1_000_000.0)
         if reuse_x is None:
             return None
-    parts = [f"cache_pct={cache_pct}"]
+    if not isinstance(window_partial, bool):
+        return None
+    parts = [
+        f"usage_scope={USAGE_METRIC_LABEL}",
+        f"window_partial={'true' if window_partial else 'false'}",
+        f"cache_pct={cache_pct}",
+    ]
     if reuse_x:
         parts.append(f"reuse_x={reuse_x}")
     return " ".join(parts)
@@ -360,6 +407,10 @@ def _read_cache(identity: dict[str, int | str], workspace_dir: str, ttl: float)
             return None
         if data.get("schema_version") != CACHE_SCHEMA_VERSION:
             return None
+        if data.get("reducer_schema") != CACHE_REDUCER_SCHEMA:
+            return None
+        if data.get("metric_label") != USAGE_METRIC_LABEL:
+            return None
         computed_at = float(data.get("computed_at", 0))
         now = time.time()
         if not math.isfinite(computed_at):
@@ -369,12 +420,22 @@ def _read_cache(identity: dict[str, int | str], workspace_dir: str, ttl: float)
         for key, value in identity.items():
             if data.get(key) != value:
                 return None
-        return _metric_parts(data.get("cache_pct"), data.get("reuse_x"))
+        return _metric_parts(
+            data.get("cache_pct"),
+            data.get("reuse_x"),
+            data.get("window_partial"),
+        )
     except Exception:
         return None
 
 
-def _write_cache(identity: dict[str, int | str], workspace_dir: str, cache_pct: str, reuse_x: str | None) -> None:
+def _write_cache(
+    identity: dict[str, int | str],
+    workspace_dir: str,
+    cache_pct: str,
+    reuse_x: str | None,
+    window_partial: bool,
+) -> None:
     ttl = _cache_ttl_seconds()
     if ttl <= 0:
         return
@@ -383,6 +444,8 @@ def _write_cache(identity: dict[str, int | str], workspace_dir: str, cache_pct:
         return
     payload = {
         "schema_version": CACHE_SCHEMA_VERSION,
+        "metric_label": USAGE_METRIC_LABEL,
+        "window_partial": window_partial,
         **identity,
         "computed_at": time.time(),
         "cache_pct": cache_pct,
@@ -418,9 +481,12 @@ def _write_cache(identity: dict[str, int | str], workspace_dir: str, cache_pct:
 
 
 def transcript_metrics(path: str, workspace_dir: str) -> str | None:
-    input_tokens = 0
-    cache_read = 0
-    cache_creation = 0
+    if UsageReducer is None or REDUCER_SCHEMA != CACHE_REDUCER_SCHEMA:
+        print(
+            "context-guard statusline: usage reducer unavailable; transcript metrics omitted",
+            file=sys.stderr,
+        )
+        return None
     try:
         opened = _open_regular_transcript(path)
         if opened is None:
@@ -437,38 +503,38 @@ def transcript_metrics(path: str, workspace_dir: str) -> str | None:
         finally:
             os.close(fd)
         lines = chunk.splitlines()
+        window_partial = size > read_size
         if size > read_size and lines:
             lines = lines[1:]
-        for raw in lines[-MAX_RECORDS:]:
-            if not raw.strip():
-                continue
+        lines = [raw for raw in lines if raw.strip()]
+        if len(lines) > MAX_RECORDS:
+            window_partial = True
+            lines = lines[-MAX_RECORDS:]
+        reducer = UsageReducer()
+        for ordinal, raw in enumerate(lines):
             try:
                 obj = json.loads(raw)
             except Exception:
+                reducer.note_invalid_row()
                 continue
-            usage = _extract_usage(obj)
-            if not usage:
-                continue
-            input_tokens += _int_or_zero(usage.get("input_tokens"))
-            cr = usage.get("cache_read_input_tokens")
-            if cr is None:
-                cr = usage.get("cacheRead")
-            cache_read += _int_or_zero(cr)
-            cc = usage.get("cache_creation_input_tokens")
-            if cc is None:
-                cc = usage.get("cacheCreation")
-            cache_creation += _int_or_zero(cc)
+            reducer.observe(
+                obj,
+                file_identity=str(identity["path_hash"]),
+                row_ordinal=ordinal,
+            )
+        reduced = reducer.finalize()
+        window_partial = window_partial or reduced.partial
+        input_tokens = reduced.tokens.get("input", 0)
+        cache_read = reduced.tokens.get("cache_read", 0)
+        cache_creation = reduced.tokens.get("cache_creation", 0)
         denom = input_tokens + cache_read + cache_creation
         if denom <= 0 or cache_read <= 0:
             return None
         pct = max(0.0, min(100.0, cache_read / denom * 100))
         cache_pct = f"{pct:.0f}"
         reuse_x = f"{cache_read / cache_creation:.1f}" if cache_creation > 0 else None
-        _write_cache(identity, workspace_dir, cache_pct, reuse_x)
-        parts = [f"cache_pct={cache_pct}"]
-        if reuse_x:
-            parts.append(f"reuse_x={reuse_x}")
-        return " ".join(parts)
+        _write_cache(identity, workspace_dir, cache_pct, reuse_x, window_partial)
+        return _metric_parts(cache_pct, reuse_x, window_partial)
     except Exception:
         return None
 
@@ -537,15 +603,26 @@ def render_statusline(payload: dict[str, Any]) -> str:
         if raw_metrics:
             cache_pct = ""
             reuse_x = ""
+            usage_scope = ""
+            window_partial = ""
             for metric in raw_metrics.split():
                 if metric.startswith("cache_pct="):
                     cache_pct = metric[len("cache_pct=") :]
                 elif metric.startswith("reuse_x="):
                     reuse_x = metric[len("reuse_x=") :]
+                elif metric.startswith("usage_scope="):
+                    usage_scope = metric[len("usage_scope=") :]
+                elif metric.startswith("window_partial="):
+                    window_partial = metric[len("window_partial=") :]
             if cache_pct:
                 metrics_label = f" | cache {sanitize_status(cache_pct)}%"
                 if reuse_x:
                     metrics_label += f" | reuse {sanitize_status(reuse_x)}x"
+                if usage_scope == USAGE_METRIC_LABEL and window_partial in {"true", "false"}:
+                    metrics_label += (
+                        f" | {USAGE_METRIC_LABEL} "
+                        f"window_partial={window_partial}"
+                    )
 
     return f"[{model}] {dir_label}{branch_label} | ctx {context_label} | cost {cost}{metrics_label}"
 
@@ -566,4 +643,4 @@ except BrokenPipeError:
     raise SystemExit(0)
 PYEOF
 
-exec python3 -c "$CONTEXT_GUARD_STATUSLINE_PY" "$@"
+exec python3 -I -c "$CONTEXT_GUARD_STATUSLINE_PY" "$@"

package/plugins/context-guard/bin/context-guard-statusline-merged

@@ -5,7 +5,7 @@
 #   ─────────────────────────────────────────────────────────────────────────
 #   OMC HUD 존재? │ token-statusline 존재? │ 출력
 #   ─────────────────────────────────────────────────────────────────────────
-#   yes           │ yes                    │ OMC HUD + cost/cache/reuse 결합 (1줄)
+#   yes           │ yes                    │ OMC HUD + cost/cache/reuse/scope 결합 (1줄)
 #   yes           │ no                     │ OMC HUD 단독
 #   no            │ yes                    │ token-statusline 단독
 #   no            │ no                     │ "[hud unavailable]"
@@ -137,8 +137,9 @@ fi
 
 # ── 3) 결합: OMC HUD 가 살아있을 때만 token 출력에서 compact extras 만 뽑아 붙임 ─
 # token-statusline 형식:
-#   "[model] dir | branch | ctx N% | cost $N.NNN | cache N% | reuse N.Nx"
-# OMC HUD 와 중복되는 model/dir/branch/ctx 는 버리고 cost/cache/reuse 만 채택한다.
+#   "[model] dir | branch | ctx N% | cost $N.NNN | cache N% | reuse N.Nx | usage_tail_v2 window_partial=BOOL"
+# OMC HUD 와 중복되는 model/dir/branch/ctx 는 버리고 cost/cache/reuse 및
+# bounded-tail scope disclosure 만 채택한다.
 extras=''
 if [[ -n "$omc_out" && -n "$tok_out" ]]; then
   if [[ "$tok_out" =~ \|[[:space:]]+cost[[:space:]]+(\$[0-9.]+|n/a) ]]; then
@@ -150,6 +151,9 @@ if [[ -n "$omc_out" && -n "$tok_out" ]]; then
   if [[ "$tok_out" =~ \|[[:space:]]+reuse[[:space:]]+([0-9]+(\.[0-9]+)?x|n/a) ]]; then
     extras+=" | reuse ${BASH_REMATCH[1]}"
   fi
+  if [[ "$tok_out" =~ \|[[:space:]]+(usage_tail_v2)[[:space:]]+(window_partial=(true|false)) ]]; then
+    extras+=" | ${BASH_REMATCH[1]} ${BASH_REMATCH[2]}"
+  fi
 fi
 
 # ── 4) 출력 ──────────────────────────────────────────────────────────────────

package/plugins/context-guard/bin/context-guard-tool-prune

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import importlib.util
 import json
 import os
 import shlex
@@ -19,6 +20,7 @@ import stat
 import sys
 import time
 from dataclasses import dataclass
+from types import ModuleType
 from typing import Any, NoReturn
 
 TOOL_NAME = "context-guard-tool-prune"
@@ -68,9 +70,6 @@ SECRET_RE = re.compile(
     r"(?<![A-Za-z0-9])(?:api[_-]?key|apikey|token|secret|password|client[_-]?secret|authorization|credential|signature|sig|private[_-]?key|privatekey|pgp[_-]?private[_-]?key|pgpprivatekey|ssh[_-]?key|sshkey|(?:aws[_-]?)?access[_-]?key(?:[_-]?id)?|awsaccesskeyid)\s*[:=]\s*[^\s,}\]]+"
     r")"
 )
-SENSITIVE_KEY_RE = re.compile(
-    r"(?i)(authorization|api[_-]?key|apikey|token|secret|password|passwd|pwd|client[_-]?secret|credential|signature|sig|x-amz-signature|x-amz-credential|awsaccesskeyid|(?:aws[_-]?)?access[_-]?key(?:[_-]?id)?|private[_-]?key|privatekey|pgp[_-]?private[_-]?key|pgpprivatekey|ssh[_-]?key|sshkey)"
-)
 VALUE_BEARING_KEY_RE = re.compile(r"(?i)^(default|const|enum|example|examples|value|values)$")
 
 
@@ -135,20 +134,52 @@ def cap_text(value: object, limit: int = MAX_LABEL_CHARS) -> str:
     return text[: max(0, limit - len(marker))] + marker
 
 
+def load_credential_policy() -> ModuleType:
+    script_dir = Path(__file__).resolve().parent
+    candidate = (
+        script_dir.parent / "lib" / "credential_policy.py"
+        if script_dir.name == "bin"
+        else script_dir / "credential_policy.py"
+    )
+    spec = importlib.util.spec_from_file_location(
+        "_context_guard_tool_prune_credential_policy",
+        candidate,
+    )
+    if spec is None or spec.loader is None:
+        raise RuntimeError(f"could not load credential policy: {candidate}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+_CREDENTIAL_POLICY = load_credential_policy()
+normalize_sensitive_key = _CREDENTIAL_POLICY.normalize_sensitive_key
+is_sensitive_key = _CREDENTIAL_POLICY.is_sensitive_key
+redact_high_confidence_credentials = _CREDENTIAL_POLICY.redact_high_confidence_credentials
+
+
 def redact_string(value: str) -> tuple[str, int]:
+    value, redactions = redact_high_confidence_credentials(value)
+
     def repl(match: re.Match[str]) -> str:
+        nonlocal redactions
         text = match.group(0)
+        replacement = "[REDACTED]"
         if "=" in text:
             key = text.split("=", 1)[0]
-            if SENSITIVE_KEY_RE.search(key):
-                return key + "=[REDACTED]"
-        if ":" in text:
+            if not is_sensitive_key(key):
+                return text
+            replacement = key + "=[REDACTED]"
+        elif ":" in text:
             key = text.split(":", 1)[0]
-            if SENSITIVE_KEY_RE.search(key):
-                return key + ": [REDACTED]"
-        return "[REDACTED]"
+            if not is_sensitive_key(key):
+                return text
+            replacement = key + ": [REDACTED]"
+        if replacement != text:
+            redactions += 1
+        return replacement
 
-    return SECRET_RE.subn(repl, value)
+    return SECRET_RE.sub(repl, value), redactions
 
 
 def redact_whole_value(value: Any) -> tuple[Any, int]:
@@ -169,6 +200,8 @@ def redact_whole_value(value: Any) -> tuple[Any, int]:
             out.append(sanitized)
             count += item_redactions
         return out, count
+    if value == "[REDACTED]":
+        return value, 0
     return "[REDACTED]", 1
 
 
@@ -191,7 +224,7 @@ def sanitize_value(value: Any, *, sensitive_context: bool = False, sensitive_sch
         for key, item in value.items():
             raw_key = str(key)
             safe_key, key_redactions = redact_string(raw_key)
-            key_sensitive = bool(SENSITIVE_KEY_RE.search(raw_key))
+            key_sensitive = is_sensitive_key(raw_key)
             value_bearing = bool(VALUE_BEARING_KEY_RE.search(raw_key))
             if key_sensitive and not isinstance(item, dict):
                 sanitized, item_redactions = sanitize_value(item, sensitive_context=True)

package/plugins/context-guard/bin/context-guard-trim-output

@@ -143,8 +143,15 @@ class UnsafeAdjacentModuleError(RuntimeError):
 
 
 class FallbackLineSanitizer:
-    def __init__(self, *, show_paths: bool = False, diagnostic: str | None = None) -> None:
+    def __init__(
+        self,
+        *,
+        show_paths: bool = False,
+        context: str = "unknown_text",
+        diagnostic: str | None = None,
+    ) -> None:
         self.show_paths = show_paths
+        self.context = context
         self.diagnostic = diagnostic
         self.diagnostic_emitted = False
         self.redactions = 0
@@ -154,8 +161,6 @@ class FallbackLineSanitizer:
             print(f"context-guard-kit: sanitizer fallback active: {self.diagnostic}", file=sys.stderr)
             self.diagnostic_emitted = True
         line = strip_ansi(raw_line)
-        if not self.show_paths:
-            line = anonymize_absolute_paths(line)
         original = line
         auth_match = FALLBACK_AUTH_HEADER_RE.match(line)
         if auth_match:
@@ -223,11 +228,31 @@ def load_adjacent_python_module(script_dir: Path, name: str, *, module_prefix: s
     module = types.ModuleType(module_name)
     module.__file__ = str(script_dir / name)
     module.__package__ = ""
-    exec(compile(source, str(script_dir / name), "exec"), module.__dict__)
+    sys.modules[module_name] = module
+    try:
+        exec(compile(source, str(script_dir / name), "exec"), module.__dict__)
+    except Exception:
+        sys.modules.pop(module_name, None)
+        raise
     return module
 
 
-def load_line_sanitizer(show_paths: bool) -> object:
+def instantiate_line_sanitizer(factory: object, *, show_paths: bool, context: str) -> object:
+    try:
+        return factory(show_paths=show_paths, context=context)  # type: ignore[operator]
+    except TypeError:
+        if context != "unknown_text":
+            raise RuntimeError(
+                "adjacent sanitizer does not support required explicit context"
+            )
+        # One compatibility window for unknown-text adjacent sanitizer stubs.
+        return factory(show_paths=show_paths)  # type: ignore[operator]
+
+
+def load_line_sanitizer(
+    show_paths: bool,
+    context: str = "unknown_text",
+) -> object:
     """Reuse the stronger sanitizer when it is shipped next to this wrapper."""
     script_dir = Path(__file__).resolve().parent
     load_errors: list[str] = []
@@ -240,14 +265,22 @@ def load_line_sanitizer(show_paths: bool) -> object:
             )
             if module is None:
                 continue
-            return module.LineSanitizer(show_paths=show_paths)
+            return instantiate_line_sanitizer(
+                module.LineSanitizer,
+                show_paths=show_paths,
+                context=context,
+            )
         except UnsafeAdjacentModuleError:
             raise
         except Exception as exc:
             load_errors.append(f"{name} failed to load: {exc.__class__.__name__}: {exc}")
             continue
     diagnostic = "; ".join(load_errors) if load_errors else "strong sanitizer not found next to trim wrapper"
-    return FallbackLineSanitizer(show_paths=show_paths, diagnostic=diagnostic)
+    return FallbackLineSanitizer(
+        show_paths=show_paths,
+        context=context,
+        diagnostic=diagnostic,
+    )
 
 
 def load_artifact_store_module() -> object:
@@ -508,7 +541,7 @@ def compact_item(
 ) -> str:
     """Normalize a failure-summary item without letting one log line dominate memory/output."""
     if sanitizer is None:
-        sanitizer = load_line_sanitizer(show_paths)
+        sanitizer = load_line_sanitizer(show_paths, context="unknown_text")
     sanitized, _ = sanitizer.sanitize(text)  # type: ignore[attr-defined]
     item = re.sub(r"\s+", " ", strip_ansi(sanitized).strip())
     if len(item) <= limit:
@@ -529,7 +562,7 @@ class RunnerFailureSummary:
     def __init__(self, max_items_per_runner: int, *, show_paths: bool = False) -> None:
         self.max_items_per_runner = max(0, max_items_per_runner)
         self.show_paths = show_paths
-        self.sanitizer = load_line_sanitizer(show_paths)
+        self.sanitizer = load_line_sanitizer(show_paths, context="unknown_text")
         self.items: dict[str, list[str]] = collections.defaultdict(list)
         self.seen: dict[str, set[str]] = collections.defaultdict(set)
         self.jest_active = False
@@ -1478,6 +1511,15 @@ def main() -> int:
             "(default: off; formats: markdown, json)"
         ),
     )
+    parser.add_argument(
+        "--digest-always",
+        action="store_true",
+        help=(
+            "keep the digest even when the command output is smaller than the digest; "
+            "by default a smaller output is passed through so the digest cannot inflate "
+            "context"
+        ),
+    )
     parser.add_argument(
         "--artifact-receipt",
         action="store_true",
@@ -1533,7 +1575,10 @@ def main() -> int:
         return 2
 
     try:
-        line_sanitizer = load_line_sanitizer(args.show_paths)
+        line_sanitizer = load_line_sanitizer(
+            args.show_paths,
+            context="unknown_text",
+        )
     except UnsafeAdjacentModuleError as exc:
         print(f"context-guard-kit: unsafe adjacent helper: {exc}", file=sys.stderr)
         return 2
@@ -1693,10 +1738,41 @@ def main() -> int:
                     )
                     if guidance not in next_queries:
                         next_queries.insert(0, guidance)
-        if args.digest == "json":
-            sys.stdout.write(render_digest_json(payload, args.max_chars))
+        rendered = (
+            render_digest_json(payload, args.max_chars)
+            if args.digest == "json"
+            else render_digest_markdown(payload, args.max_chars)
+        )
+        # digest 는 큰 출력을 줄이려는 기능이다. 출력이 작으면 digest 가 오히려 커져서
+        # 컨텍스트를 늘리므로, 그럴 때는 원래 출력을 그대로 통과시킨다. artifact receipt 를
+        # 저장한 경우에는 handle/재확장 명령이 digest 의 존재 이유이므로 폴백하지 않는다.
+        passthrough = "".join(all_lines)
+        marker = (
+            "[context-guard-kit] digest skipped: it was larger than the command output\n"
+        )
+        digest_bytes = len(rendered.encode("utf-8"))
+        passthrough_bytes = len(passthrough.encode("utf-8")) + len(marker.encode("utf-8"))
+        # 폴백 조건은 보수적으로 둔다.
+        # - 전체 출력이 예산 안에 들어와 all_lines 가 완전한 출력일 때만 통과시킨다.
+        #   그렇지 않으면 잘린 출력을 원본처럼 내보내 정보를 잃는다.
+        # - 실패한 명령에서는 digest 가 종료 코드/실패 signature 를 담으므로 유지한다.
+        # - artifact receipt 를 요청했다면 handle/재확장 명령이 digest 의 존재 이유다.
+        complete_output_available = (
+            total <= args.max_lines
+            and visible_chars <= args.max_chars
+            and not any_line_capped
+        )
+        if (
+            not args.digest_always
+            and not args.artifact_receipt
+            and rc == 0
+            and complete_output_available
+            and passthrough_bytes < digest_bytes
+        ):
+            sys.stdout.write(marker)
+            sys.stdout.write(passthrough)
         else:
-            sys.stdout.write(render_digest_markdown(payload, args.max_chars))
+            sys.stdout.write(rendered)
         artifact_capture.close()
         return rc
 

package/plugins/context-guard/brief/README.md

@@ -70,3 +70,22 @@ Each block is wrapped in stable markers:
 To remove brief mode, delete the block between (and including) those two marker lines. Only
 one brief-mode block should be present at a time; installing a different level replaces the
 existing block rather than stacking a second one.
+
+## Quiet narration is separate
+
+[`narration-mode.quiet.md`](narration-mode.quiet.md) is a default-off, Claude-only rule for
+reducing discretionary progress narration. It is not a brief-mode level and does not change
+final-answer requirements or reasoning depth. Manage it only through the isolated,
+project-scoped rules operation:
+
+```bash
+context-guard setup --rules-only --agent claude --scope project --narration-mode quiet --plan
+context-guard setup --rules-only --agent claude --scope project --narration-mode quiet --yes
+context-guard setup --rules-only --agent claude --scope project --narration-mode default --yes
+```
+
+This operation manages only the ContextGuard narration span in project `CLAUDE.md`; it does
+not read or change Claude settings, hooks, permissions, statusline, model defaults, or other
+agents' rule files. The rule preserves approvals and decisions, blockers, failures,
+destructive or security warnings, required progress, final results, changed files, and
+verification. It is best-effort guidance and does not guarantee token or cost savings.

package/plugins/context-guard/brief/narration-mode.quiet.md

@@ -0,0 +1,21 @@
+<!-- BEGIN context-guard:narration-mode mode=quiet version=1 -->
+## 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.
+<!-- END context-guard:narration-mode -->