@ictechgy/context-guard 0.4.9 → 0.4.10

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

@@ -21,6 +21,11 @@
 #                              (미지정 시 자기 옆 디렉토리만 사용; PATH 탐색 안 함)
 set -u
 
+if [[ "${1:-}" == "--help" || "${1:-}" == "-h" ]]; then
+  printf 'ContextGuard helper: context-guard-statusline-merged\n'
+  exit 0
+fi
+
 statusline_input_tmp=''
 
 statusline_tmp_base() {

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

@@ -23,14 +23,20 @@ from typing import Any, NoReturn
 
 TOOL_NAME = "context-guard-tool-prune"
 SCHEMA_VERSION = "contextguard.tool-prune.v1"
+DEFER_SCHEMA_VERSION = "contextguard.tool-prune.defer.v1"
 DEFAULT_STORE_DIR = ".context-guard/tool-prune"
 DEFAULT_TOP = 5
+DEFAULT_CORE_TOP = 3
+DEFAULT_DEFERRED_TOP = 20
+DEFAULT_NAMESPACE_TOP = 20
 DEFAULT_BUDGET_BYTES = 12_000
 DEFAULT_MAX_CATALOG_BYTES = 1_000_000
 DEFAULT_MAX_OUTPUT_BYTES = 65_536
 DEFAULT_MAX_PAYLOAD_BYTES = 1_048_576
 DEFAULT_MAX_RECEIPT_BYTES = 16_384
 MAX_TOP = 200
+MAX_DEFERRED_TOP = 1_000
+MAX_NAMESPACE_TOP = 200
 MAX_LABEL_CHARS = 160
 MAX_DESCRIPTION_CHARS = 360
 MAX_OMITTED_TOOLS = 30
@@ -94,13 +100,17 @@ def byte_len_json(data: Any) -> int:
     return byte_len_text(json_bytes(data))
 
 
+def proxy_tokens(chars: int) -> int:
+    return max(0, (int(chars) + TOKEN_PROXY_CHARS_PER_TOKEN - 1) // TOKEN_PROXY_CHARS_PER_TOKEN)
+
+
 def sha256_text(text: str) -> str:
     return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
 
 
 def bounded_int(value: object, *, default: int, minimum: int, maximum: int, name: str) -> int:
     try:
-        number = int(value)
+        number = int(default if value is None else value)
     except (TypeError, ValueError, OverflowError):
         fail(f"{name} must be an integer")
     if number < minimum:
@@ -583,6 +593,86 @@ def selected_tool_record(cand: Candidate, receipt_id: str, budget_left: int, *,
     return record, 0
 
 
+def deferred_tool_record(cand: Candidate, receipt_id: str, *, store_dir: str) -> dict[str, Any]:
+    return {
+        "name": cand.name,
+        "server": cand.server,
+        "score": cand.score,
+        "rank": cand.rank,
+        "description": cand.description,
+        "schema_bytes": byte_len_json(cand.schema),
+        "reason": "deferred_after_core_top",
+        "retrieval": retrieval_command(receipt_id, store_dir=store_dir, tool_name=cand.name),
+    }
+
+
+def namespace_records(
+    ranked: list[Candidate],
+    core_names: set[str],
+    deferred_names: set[str],
+    receipt_id: str,
+    *,
+    store_dir: str,
+    namespace_top: int,
+) -> tuple[list[dict[str, Any]], int]:
+    grouped: dict[str, dict[str, Any]] = {}
+    for cand in ranked:
+        namespace = cand.server or "local"
+        item = grouped.setdefault(
+            namespace,
+            {
+                "namespace": namespace,
+                "tool_count": 0,
+                "core_count": 0,
+                "listed_deferred_count": 0,
+                "sample_tools": [],
+                "retrieval": retrieval_command(receipt_id, store_dir=store_dir),
+            },
+        )
+        item["tool_count"] += 1
+        if cand.name in core_names:
+            item["core_count"] += 1
+        if cand.name in deferred_names:
+            item["listed_deferred_count"] += 1
+        samples = item["sample_tools"]
+        if isinstance(samples, list) and len(samples) < 8:
+            samples.append(cand.name)
+    records = sorted(grouped.values(), key=lambda item: (-int(item["listed_deferred_count"]), str(item["namespace"])))
+    return records[:namespace_top], max(0, len(records) - namespace_top)
+
+
+def build_receipt_and_payload(ranked: list[Candidate], safe_query: str, total_redactions: int, *, store_dir_arg: str, max_payload_bytes: int, max_receipt_bytes: int) -> tuple[str, dict[str, Any], dict[str, Any], Path, Path, Path, int, int]:
+    payload_without_id = build_payload("pending", ranked, safe_query, total_redactions)
+    receipt_id = build_receipt_id(payload_without_id)
+    payload = build_payload(receipt_id, ranked, safe_query, total_redactions)
+    payload_text = json_bytes(payload, indent=2) + "\n"
+    payload_bytes = byte_len_text(payload_text)
+    if payload_bytes > max_payload_bytes:
+        fail(f"payload exceeds --max-payload-bytes: {payload_bytes} > {max_payload_bytes}")
+    payload_sha = sha256_text(payload_text.rstrip("\n"))
+
+    store_dir, receipt_path, payload_path = store_paths(store_dir_arg, receipt_id)
+    receipt = {
+        "tool": TOOL_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "receipt_id": receipt_id,
+        "created_at_unix": int(time.time()),
+        "path": display_path(receipt_path),
+        "payload_path": display_path(payload_path),
+        "payload_sha256": payload_sha,
+        "payload_bytes": payload_bytes,
+        "contains": "compact_metadata_plus_sanitized_payload",
+        "tool_count": len(ranked),
+        "tools": [cand.name for cand in ranked[:50]],
+        "tools_truncated": len(ranked) > 50,
+        "retrieval_hint": retrieval_command(receipt_id, store_dir=store_dir_arg, tool_name="<name>"),
+    }
+    receipt_size = byte_len_text(json_bytes(receipt, indent=2) + "\n")
+    if receipt_size > max_receipt_bytes:
+        fail(f"receipt exceeds --max-receipt-bytes: {receipt_size} > {max_receipt_bytes}")
+    return receipt_id, payload, receipt, store_dir, receipt_path, payload_path, payload_bytes, receipt_size
+
+
 def shrink_result_for_output(result: dict[str, Any], max_output_bytes: int) -> str:
     candidate = json_bytes(result, indent=2) + "\n"
     if byte_len_text(candidate) <= max_output_bytes:
@@ -591,6 +681,7 @@ def shrink_result_for_output(result: dict[str, Any], max_output_bytes: int) -> s
     result = json.loads(json_bytes(result))
     omitted = result.get("omitted_tools")
     while isinstance(omitted, list) and len(omitted) > 0:
+        # The list is halved on each pass, so even a one-item list converges.
         keep = max(0, len(omitted) // 2)
         result["omitted_tools"] = omitted[:keep]
         result["omitted_tools_truncated"] = True
@@ -699,6 +790,138 @@ def select_catalog(args: argparse.Namespace) -> str:
     return rendered
 
 
+def defer_report(args: argparse.Namespace) -> str:
+    max_catalog_bytes = bounded_int(args.max_catalog_bytes, default=DEFAULT_MAX_CATALOG_BYTES, minimum=1, maximum=100_000_000, name="--max-catalog-bytes")
+    max_output_bytes = bounded_int(args.max_output_bytes, default=DEFAULT_MAX_OUTPUT_BYTES, minimum=1, maximum=10_000_000, name="--max-output-bytes")
+    max_payload_bytes = bounded_int(args.max_payload_bytes, default=DEFAULT_MAX_PAYLOAD_BYTES, minimum=1, maximum=100_000_000, name="--max-payload-bytes")
+    max_receipt_bytes = bounded_int(args.max_receipt_bytes, default=DEFAULT_MAX_RECEIPT_BYTES, minimum=1, maximum=10_000_000, name="--max-receipt-bytes")
+    core_top = bounded_int(args.core_top, default=DEFAULT_CORE_TOP, minimum=1, maximum=MAX_TOP, name="--core-top")
+    deferred_top = bounded_int(args.deferred_top, default=DEFAULT_DEFERRED_TOP, minimum=0, maximum=MAX_DEFERRED_TOP, name="--deferred-top")
+    namespace_top = bounded_int(args.namespace_top, default=DEFAULT_NAMESPACE_TOP, minimum=0, maximum=MAX_NAMESPACE_TOP, name="--namespace-top")
+    budget_bytes = bounded_int(args.budget_bytes, default=DEFAULT_BUDGET_BYTES, minimum=0, maximum=100_000_000, name="--budget-bytes")
+
+    text = read_limited_path(Path(args.catalog), max_catalog_bytes) if args.catalog else read_limited_stdin(max_catalog_bytes)
+    raw, redactions = parse_catalog_text(text)
+    raw_query = args.query or ""
+    safe_query, query_redactions = redact_string(raw_query)
+    total_redactions = redactions + query_redactions
+    ranked = rank_candidates(normalize_catalog(raw), raw_query)
+    (
+        receipt_id,
+        payload,
+        receipt,
+        store_dir,
+        receipt_path,
+        payload_path,
+        payload_bytes,
+        receipt_size,
+    ) = build_receipt_and_payload(
+        ranked,
+        safe_query,
+        total_redactions,
+        store_dir_arg=args.store_dir,
+        max_payload_bytes=max_payload_bytes,
+        max_receipt_bytes=max_receipt_bytes,
+    )
+
+    core_candidates = ranked[:core_top]
+    deferred_candidates = ranked[core_top:core_top + deferred_top]
+    core_tools: list[dict[str, Any]] = []
+    core_schema_bytes = 0
+    for cand in core_candidates:
+        record, used = selected_tool_record(cand, receipt_id, budget_bytes - core_schema_bytes, store_dir=args.store_dir)
+        core_schema_bytes += used
+        core_tools.append(record)
+    deferred_tools = [deferred_tool_record(cand, receipt_id, store_dir=args.store_dir) for cand in deferred_candidates]
+    core_names = {cand.name for cand in core_candidates}
+    deferred_names = {cand.name for cand in deferred_candidates}
+    deferred_namespaces, deferred_namespaces_truncated_count = namespace_records(
+        ranked,
+        core_names,
+        deferred_names,
+        receipt_id,
+        store_dir=args.store_dir,
+        namespace_top=namespace_top,
+    )
+    all_schema_bytes = sum(byte_len_json(cand.schema) for cand in ranked)
+    tool_stub_report_bytes = byte_len_json(core_tools) + byte_len_json(deferred_tools)
+    result = {
+        "tool": TOOL_NAME,
+        "schema_version": DEFER_SCHEMA_VERSION,
+        "mode": "defer-report",
+        "query": safe_query,
+        "core_top": core_top,
+        "deferred_top": deferred_top,
+        "namespace_top": namespace_top,
+        "candidate_count": len(ranked),
+        "native_provider_integration": False,
+        "core_tools": core_tools,
+        "deferred_tools": deferred_tools,
+        "listed_deferred_count": len(deferred_tools),
+        "total_deferred_count": max(0, len(ranked) - core_top),
+        "deferred_tools_truncated_count": max(0, len(ranked) - core_top - len(deferred_tools)),
+        "deferred_namespaces": deferred_namespaces,
+        "deferred_namespaces_truncated_count": deferred_namespaces_truncated_count,
+        "receipt": {
+            **receipt,
+            "bytes": receipt_size,
+        },
+        "token_proxy": {
+            "measurement": "estimated",
+            "method": "char4_proxy",
+            "chars_per_token": TOKEN_PROXY_CHARS_PER_TOKEN,
+            "all_schema_bytes": all_schema_bytes,
+            "tool_stub_report_bytes": tool_stub_report_bytes,
+            "all_schema_tokens_estimated": proxy_tokens(all_schema_bytes),
+            "tool_stub_report_tokens_estimated": proxy_tokens(tool_stub_report_bytes),
+            "claim_boundary": "proxy_only_not_provider_billed_tokens",
+        },
+        "provider_patterns": [
+            {
+                "provider": "openai",
+                "pattern": "Keep only core tool schemas inline; retrieve deferred schemas through app/tool-search plumbing or the local receipt before invoking a deferred tool.",
+                "native_provider_integration": False,
+            },
+            {
+                "provider": "anthropic",
+                "pattern": "Keep stable, frequently used tool definitions in the cacheable prefix; treat deferred tools as application-managed retrieval, not Claude-native lazy loading.",
+                "native_provider_integration": False,
+            },
+            {
+                "provider": "gemini",
+                "pattern": "Group large tool catalogs by namespace and load only the task-relevant subset before the model call; verify any platform-native tool retrieval separately.",
+                "native_provider_integration": False,
+            },
+        ],
+        "claim_boundary": {
+            "advisory_only": True,
+            "native_provider_integration": False,
+            "provider_tool_search_configured": False,
+            "hosted_api_token_or_cost_savings_claim_allowed": False,
+            "requires_provider_measured_matched_tasks_for_savings_claims": True,
+        },
+        "redaction": {"redacted_values": total_redactions},
+        "caveats": [
+            "Deferred loading is an application strategy report, not a native provider integration.",
+            "Token proxy values are char/4 estimates over sanitized local JSON, not billed provider tokens.",
+            "Use receipt get commands to retrieve full sanitized schemas before using deferred tools.",
+        ],
+    }
+    rendered = json_bytes(result, indent=2) + "\n"
+    if byte_len_text(rendered) > max_output_bytes:
+        fail(f"defer report exceeds --max-output-bytes: {byte_len_text(rendered)} > {max_output_bytes}")
+
+    # Only write after every size gate has passed, so failures leave no success receipt.
+    ensure_private_dir(store_dir)
+    written_payload_bytes = write_private_json_atomic(payload_path, payload, max_bytes=max_payload_bytes, label="payload")
+    if written_payload_bytes != payload_bytes:
+        fail("payload byte size changed during write")
+    written_receipt_bytes = write_private_json_atomic(receipt_path, receipt, max_bytes=max_receipt_bytes, label="receipt")
+    if written_receipt_bytes != receipt_size:
+        fail("receipt byte size changed during write")
+    return rendered
+
+
 def payload_path_from_receipt(store_dir: Path, receipt_id: str, receipt: dict[str, Any]) -> Path:
     expected_name = f"{receipt_id}.payload.json"
     raw = str(receipt.get("payload_path") or "")
@@ -803,6 +1026,20 @@ def build_parser() -> argparse.ArgumentParser:
     select.add_argument("--store-dir", default=DEFAULT_STORE_DIR, help=f"receipt/payload directory (default: {DEFAULT_STORE_DIR})")
     select.add_argument("--json", action="store_true", help="emit JSON (default and only stable output contract)")
 
+    defer = sub.add_parser("defer-report", help="split a local catalog into core inline tools plus deferred receipt-backed tools")
+    defer.add_argument("--catalog", help="catalog JSON path; stdin is used when omitted")
+    defer.add_argument("--query", default="", help="task query used for lexical ranking")
+    defer.add_argument("--core-top", default=DEFAULT_CORE_TOP, help=f"number of core inline tools (default: {DEFAULT_CORE_TOP})")
+    defer.add_argument("--deferred-top", default=DEFAULT_DEFERRED_TOP, help=f"number of deferred tool stubs to list (default: {DEFAULT_DEFERRED_TOP})")
+    defer.add_argument("--namespace-top", default=DEFAULT_NAMESPACE_TOP, help=f"number of deferred namespace summaries to list (default: {DEFAULT_NAMESPACE_TOP})")
+    defer.add_argument("--budget-bytes", default=DEFAULT_BUDGET_BYTES, help=f"inline core schema byte budget (default: {DEFAULT_BUDGET_BYTES})")
+    defer.add_argument("--max-catalog-bytes", default=DEFAULT_MAX_CATALOG_BYTES, help=f"maximum catalog JSON bytes (default: {DEFAULT_MAX_CATALOG_BYTES})")
+    defer.add_argument("--max-output-bytes", default=DEFAULT_MAX_OUTPUT_BYTES, help=f"maximum rendered defer JSON bytes (default: {DEFAULT_MAX_OUTPUT_BYTES})")
+    defer.add_argument("--max-payload-bytes", default=DEFAULT_MAX_PAYLOAD_BYTES, help=f"maximum sanitized payload bytes (default: {DEFAULT_MAX_PAYLOAD_BYTES})")
+    defer.add_argument("--max-receipt-bytes", default=DEFAULT_MAX_RECEIPT_BYTES, help=f"maximum compact receipt bytes (default: {DEFAULT_MAX_RECEIPT_BYTES})")
+    defer.add_argument("--store-dir", default=DEFAULT_STORE_DIR, help=f"receipt/payload directory (default: {DEFAULT_STORE_DIR})")
+    defer.add_argument("--json", action="store_true", help="emit JSON (default and only stable output contract)")
+
     get = sub.add_parser("get", help="retrieve a full sanitized schema from a receipt payload")
     get.add_argument("receipt_id", help="receipt id returned by select")
     get.add_argument("--tool", help="tool name to retrieve; omit to list available names")
@@ -821,6 +1058,9 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "select":
             sys.stdout.write(select_catalog(args))
             return 0
+        if args.command == "defer-report":
+            sys.stdout.write(defer_report(args))
+            return 0
         if args.command == "get":
             sys.stdout.write(get_schema(args))
             return 0

package/plugins/context-guard/lib/context_guard_commands.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Canonical ContextGuard command/package manifest.
+
+This module is intentionally side-effect free. It centralizes command, copy,
+package, and smoke-test inventories that were previously repeated across the
+runtime dispatcher, release gates, sync tooling, smoke tests, and unit tests.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+IMPLEMENTATION_PAIRS: tuple[tuple[str, str], ...] = (
+    ("context_guard_cli.py", "context-guard"),
+    ("cost_guard.py", "context-guard-cost"),
+    ("cache_score.py", "context-guard-cache-score"),
+    ("benchmark_runner.py", "context-guard-bench"),
+    ("context_escrow.py", "context-guard-artifact"),
+    ("context_compress.py", "context-guard-compress"),
+    ("context_pack.py", "context-guard-pack"),
+    ("context_filter.py", "context-guard-filter"),
+    ("tool_schema_pruner.py", "context-guard-tool-prune"),
+    ("claude_transcript_cost_audit.py", "context-guard-audit"),
+    ("context_guard_diet.py", "context-guard-diet"),
+    ("experimental_registry.py", "context-guard-experiments"),
+    ("failed_attempt_nudge.py", "context-guard-failed-nudge"),
+    ("guard_large_read.py", "context-guard-guard-read"),
+    ("read_symbol.py", "context-guard-read-symbol"),
+    ("rewrite_bash_for_token_budget.py", "context-guard-rewrite-bash"),
+    ("sanitize_output.py", "context-guard-sanitize-output"),
+    ("setup_wizard.py", "context-guard-setup"),
+    ("statusline.sh", "context-guard-statusline"),
+    ("statusline_merged.sh", "context-guard-statusline-merged"),
+    ("trim_command_output.py", "context-guard-trim-output"),
+)
+
+HELPER_PAIRS: tuple[tuple[str, str], ...] = (
+    ("hook_secret_patterns.py", "lib/hook_secret_patterns.py"),
+    ("context_guard_commands.py", "lib/context_guard_commands.py"),
+)
+
+NPM_BINS: tuple[str, ...] = (
+    "context-guard",
+    "context-guard-cost",
+    "context-guard-cache-score",
+    "context-guard-bench",
+    "context-guard-artifact",
+    "context-guard-compress",
+    "context-guard-pack",
+    "context-guard-filter",
+    "context-guard-tool-prune",
+    "context-guard-audit",
+    "context-guard-diet",
+    "context-guard-experiments",
+    "context-guard-failed-nudge",
+    "context-guard-guard-read",
+    "context-guard-read-symbol",
+    "context-guard-rewrite-bash",
+    "context-guard-sanitize-output",
+    "context-guard-setup",
+    "context-guard-statusline",
+    "context-guard-statusline-merged",
+    "context-guard-trim-output",
+)
+NPM_BIN_PATHS: dict[str, str] = {
+    name: f"plugins/context-guard/bin/{name}" for name in NPM_BINS
+}
+
+DISPATCHER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
+    "setup": ("context-guard-setup",),
+    "doctor": ("context-guard-setup", "--verify"),
+    "audit": ("context-guard-audit",),
+    "diet": ("context-guard-diet",),
+    "experiments": ("context-guard-experiments",),
+    "scan": ("context-guard-diet", "scan"),
+    "trim-output": ("context-guard-trim-output",),
+    "trim": ("context-guard-trim-output",),
+    "sanitize-output": ("context-guard-sanitize-output",),
+    "sanitize": ("context-guard-sanitize-output",),
+    "filter": ("context-guard-filter",),
+    "artifact": ("context-guard-artifact",),
+    "pack": ("context-guard-pack",),
+    "tool-prune": ("context-guard-tool-prune",),
+    "compress": ("context-guard-compress",),
+    "cost": ("context-guard-cost",),
+    "route-advisor": ("context-guard-cost", "route-advisor"),
+    "route": ("context-guard-cost", "route-advisor"),
+    "cache-score": ("context-guard-cache-score",),
+    "bench": ("context-guard-bench",),
+    "read-symbol": ("context-guard-read-symbol",),
+    "rewrite-bash": ("context-guard-rewrite-bash",),
+    "guard-read": ("context-guard-guard-read",),
+    "failed-nudge": ("context-guard-failed-nudge",),
+    "statusline": ("context-guard-statusline",),
+    "statusline-merged": ("context-guard-statusline-merged",),
+}
+
+LEGACY_WRAPPERS: tuple[str, ...] = (
+    "claude-read-symbol",
+    "claude-sanitize-output",
+    "claude-token-artifact",
+    "claude-token-audit",
+    "claude-token-bench",
+    "claude-token-diet",
+    "claude-token-failed-nudge",
+    "claude-token-guard-read",
+    "claude-token-rewrite-bash",
+    "claude-token-setup",
+    "claude-token-statusline",
+    "claude-token-statusline-merged",
+    "claude-trim-output",
+)
+
+ENTRYPOINT_SMOKE_CASES: dict[str, dict[str, Any]] = {
+    "context-guard": {"args": ["--version"], "mode": "text"},
+    "context-guard-read-symbol": {"args": ["--help"], "mode": "text"},
+    "context-guard-sanitize-output": {"args": ["--help"], "mode": "text"},
+    "context-guard-artifact": {"args": ["--help"], "mode": "text"},
+    "context-guard-audit": {"args": ["--help"], "mode": "text"},
+    "context-guard-bench": {"args": ["--help"], "mode": "text"},
+    "context-guard-compress": {"args": ["--help"], "mode": "text"},
+    "context-guard-cost": {"args": ["--help"], "mode": "text"},
+    "context-guard-cache-score": {"args": ["--help"], "mode": "text"},
+    "context-guard-pack": {"args": ["--help"], "mode": "text"},
+    "context-guard-tool-prune": {"args": ["--help"], "mode": "text"},
+    "context-guard-diet": {"args": ["--help"], "mode": "text"},
+    "context-guard-experiments": {"args": ["--help"], "mode": "text"},
+    "context-guard-failed-nudge": {"args": [], "mode": "hook-json"},
+    "context-guard-filter": {"args": ["--help"], "mode": "text"},
+    "context-guard-guard-read": {"args": [], "mode": "hook-json"},
+    "context-guard-rewrite-bash": {"args": [], "mode": "hook-json"},
+    "context-guard-setup": {"args": ["--help"], "mode": "text"},
+    "context-guard-statusline": {"args": [], "mode": "statusline"},
+    "context-guard-statusline-merged": {"args": [], "mode": "statusline"},
+    "context-guard-trim-output": {"args": ["--help"], "mode": "text"},
+    # Legacy wrappers kept so existing automation does not break during the rebrand.
+    "claude-read-symbol": {"args": ["--help"], "mode": "text"},
+    "claude-sanitize-output": {"args": ["--help"], "mode": "text"},
+    "claude-token-artifact": {"args": ["--help"], "mode": "text"},
+    "claude-token-audit": {"args": ["--help"], "mode": "text"},
+    "claude-token-bench": {"args": ["--help"], "mode": "text"},
+    "claude-token-diet": {"args": ["--help"], "mode": "text"},
+    "claude-token-failed-nudge": {"args": [], "mode": "hook-json"},
+    "claude-token-guard-read": {"args": [], "mode": "hook-json"},
+    "claude-token-rewrite-bash": {"args": [], "mode": "hook-json"},
+    "claude-token-setup": {"args": ["--help"], "mode": "text"},
+    "claude-token-statusline": {"args": [], "mode": "statusline"},
+    "claude-token-statusline-merged": {"args": [], "mode": "statusline"},
+    "claude-trim-output": {"args": ["--help"], "mode": "text"},
+}
+
+PLUGIN_ENTRYPOINTS: tuple[str, ...] = (
+    "claude-read-symbol",
+    "claude-sanitize-output",
+    "claude-token-artifact",
+    "claude-token-audit",
+    "claude-token-bench",
+    "claude-token-diet",
+    "claude-token-failed-nudge",
+    "claude-token-guard-read",
+    "claude-token-rewrite-bash",
+    "claude-token-setup",
+    "claude-token-statusline",
+    "claude-token-statusline-merged",
+    "claude-trim-output",
+    "context-guard",
+    "context-guard-artifact",
+    "context-guard-audit",
+    "context-guard-bench",
+    "context-guard-compress",
+    "context-guard-cost",
+    "context-guard-cache-score",
+    "context-guard-diet",
+    "context-guard-experiments",
+    "context-guard-failed-nudge",
+    "context-guard-filter",
+    "context-guard-guard-read",
+    "context-guard-pack",
+    "context-guard-read-symbol",
+    "context-guard-rewrite-bash",
+    "context-guard-sanitize-output",
+    "context-guard-setup",
+    "context-guard-statusline",
+    "context-guard-statusline-merged",
+    "context-guard-tool-prune",
+    "context-guard-trim-output",
+)
+
+DISPATCHER_SMOKE_CASES: tuple[dict[str, Any], ...] = (
+    {"entrypoint": "context-guard", "args": ["experiments", "list", "--json"], "mode": "json"},
+    {"entrypoint": "context-guard", "args": ["cost", "--help"], "mode": "text"},
+    {"entrypoint": "context-guard", "args": ["route-advisor", "--help"], "mode": "text"},
+    {"entrypoint": "context-guard", "args": ["cache-score", "--help"], "mode": "text"},
+    {"entrypoint": "context-guard-pack", "args": ["suggest", "--help"], "mode": "text"},
+    {"entrypoint": "context-guard-pack", "args": ["auto", "--help"], "mode": "text"},
+)
+
+
+def expected_command_pack_files() -> tuple[str, ...]:
+    # npm packages ship the plugin-local executable/helper copies only. The
+    # checkout-local ``context-guard-kit`` files remain the source of truth for
+    # maintainers and are kept byte-synchronized with these packaged copies by
+    # ``scripts/sync_plugin_copies.py`` and ``scripts/prepublish_check.py``.
+    files = {f"plugins/context-guard/bin/{bin_name}" for _kit_name, bin_name in IMPLEMENTATION_PAIRS}
+    files.update(f"plugins/context-guard/{plugin_rel}" for _kit_name, plugin_rel in HELPER_PAIRS)
+    files.update(f"plugins/context-guard/bin/{wrapper}" for wrapper in LEGACY_WRAPPERS)
+    return tuple(sorted(files))

package/plugins/context-guard/skills/setup/SKILL.md

@@ -40,3 +40,4 @@ Safety:
 - Prefer project-local `.claude/settings.json`.
 - `context-guard-setup --verify` is a local read-only health check and never applies settings.
 - Setup's post-apply scan is local, read-only, and prints a summary only; it does not mutate settings.
+- Setup should use packaged/check-out helper paths by default; only pass `--allow-path-helper-fallback` when the user explicitly trusts a PATH-installed ContextGuard helper set.

package/context-guard-kit/README.md

@@ -1,91 +0,0 @@
-# ContextGuard Kit
-
-Claude Code CLI 컨텍스트 낭비를 줄이기 위한 실험용 도구 모음입니다. 모두 Python/Bash 표준 기능만 사용합니다.
-
-## 구성
-
-- `statusline.sh` — context/cost/model을 상태표시줄에 표시합니다.
-- `trim_command_output.py` — 긴 명령 출력을 head/tail/error와 pytest/Jest/Vitest/Go/Rust 실패 요약 중심으로 축약하고 원래 종료 코드를 보존합니다.
-- `rewrite_bash_for_token_budget.py` — Claude Code `PreToolUse` hook에서 test/build/lint 명령을 wrapper로 감쌉니다.
-- `claude_transcript_cost_audit.py` — `~/.claude/projects` JSONL transcript에서 usage/cost/cache 필드와 캐시 친화적 프롬프트 배치 신호를 집계하고 `--recommend`로 절감 액션을 제안합니다.
-- `context_guard_diet.py` — 프로젝트 `.claude/settings.json`의 deny/hook/statusline, 여러 AI 에이전트 규칙 파일의 컨텍스트 비대화, 로컬 context-exclusion 추천, structural-waste 진단을 스캔합니다.
-- `guard_large_read.py` — Claude Code `PreToolUse` Read hook에서 큰 파일 전체 읽기를 막고 symbol/line-range 읽기로 유도합니다.
-- `read_symbol.py` — Python/JS/TS/Go/Rust 파일에서 지정 symbol 주변만 출력합니다.
-- `sanitize_output.py` — `rg`/`grep`/`git diff` 같은 검색·diff 출력에서 자격 증명처럼 보이는 값을 가리고 head/anchor/tail로 축약합니다.
-- `context_escrow.py` — 큰 명령 출력을 정제한 뒤 로컬 artifact로 저장하고 line/pattern query로 다시 조회합니다.
-- `context_pack.py` — 우선순위가 있는 로컬 파일 근거를 바이트 예산 안의 Markdown context pack으로 조립하고, 로컬 query/diff/output 신호에서 build manifest를 추천합니다.
-- `context_filter.py` — 사용자 소유 JSON DSL로 성공 출력 라인 필터를 적용하되, 보호해야 할 실패 출력은 원문 그대로 통과시킵니다.
-- `tool_schema_pruner.py` — 로컬 tool/MCP catalog를 top-k schema 자문 리포트로 줄이고, 전체 정제된 schema는 receipt/payload로 재조회할 수 있게 합니다.
-- `benchmark_runner.py` — 고정 task/variant fixture로 A/B token/cost 절감 benchmark, cost-shift ledger, report를 생성합니다.
-- `setup_wizard.py` — 설치 후 project-local `.claude/settings.json`을 대화형으로 선택하고 병합합니다.
-- `failed_attempt_nudge.py` — 반복 Bash 실패 시 `/clear`/`/compact`와 전략 전환을 짧게 권유합니다.
-- `settings.example.json` — project `.claude/settings.json` 예시입니다.
-
-## 빠른 실험
-
-```bash
-python3 context-guard-kit/trim_command_output.py --max-lines 80 -- bash -lc 'seq 1 1000; echo FAIL test_x >&2; exit 1'
-python3 context-guard-kit/trim_command_output.py --max-lines 80 -- pytest tests -q
-python3 context-guard-kit/claude_transcript_cost_audit.py ~/.claude/projects --top 10 --recommend
-python3 context-guard-kit/setup_wizard.py
-python3 context-guard-kit/context_guard_diet.py scan . --json
-python3 context-guard-kit/context_guard_diet.py structural-waste . --tool-catalog tools.json --log-path .claude --json
-python3 context-guard-kit/context_filter.py validate --config .context-guard/filter-dsl.json --json
-python3 context-guard-kit/context_filter.py run --config .context-guard/filter-dsl.json -- git status --short
-python3 context-guard-kit/read_symbol.py path/to/file.py TargetSymbol
-long-command 2>&1 | python3 context-guard-kit/context_escrow.py store --command "long-command" --json
-python3 context-guard-kit/context_escrow.py get <artifact_id> --lines 1:80
-python3 context-guard-kit/context_pack.py suggest --root . --query "failing tests review" --diff HEAD --manifest-out suggested-pack.json --budget-bytes 12000 --json
-python3 context-guard-kit/context_pack.py build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
-python3 context-guard-kit/context_pack.py slice --root . --path README.md --lines 1:40 --json
-python3 context-guard-kit/tool_schema_pruner.py select --catalog tools.json --query "review failing tests" --top 5 --budget-bytes 12000 --json
-python3 context-guard-kit/tool_schema_pruner.py get <receipt_id> --tool read_file --json
-python3 context-guard-kit/benchmark_runner.py --tasks bench/tasks.json --variants bench/variants.json --csv bench/results.csv --ledger-jsonl bench/cost-shift.jsonl --report-json bench/report.json
-python3 context-guard-kit/sanitize_output.py -- rg -n "TOKEN|SECRET" .
-python3 context-guard-kit/sanitize_output.py -- git diff
-```
-
-`trim_command_output.py`는 output이 budget을 넘을 때 runner별 failure summary를 먼저 보여줍니다. 예를 들어 pytest node id, Jest/Vitest 실패 파일/테스트, `go test`의 실패 test와 `_test.go:line`, `cargo test` panic 위치를 짧게 보존해 Claude가 전체 로그를 다시 읽지 않고도 다음에 수정할 파일을 고를 수 있게 합니다. head/tail 로그 대신 더 작은 의미 요약만 필요하면 `--digest markdown` 또는 `--digest json`을 추가하세요. digest mode는 status, exit code, truncation count, runner failure facts, 정제된 failure signature, 중복 라인 그룹, 대표 라인, redaction count, 다음 query 제안을 남깁니다. digest mode에 `--artifact-receipt`를 더하면 sanitized 전체 output을 로컬 `context-guard-artifact` receipt로 보관하고, 출력된 `context-guard-artifact get ...` 명령으로 누락된 부분을 정확히 다시 조회할 수 있습니다. 감싼 명령은 기본 600초 후 timeout 처리되며(`--timeout-seconds`로 조정), 가능한 환경에서는 process group까지 종료한 뒤 124를 반환합니다. ANSI color code는 제거하며, 절대경로는 기본적으로 `basename#path:<hash>`로 익명화합니다. 로컬 디버깅에서 원문 절대경로가 꼭 필요하면 `--show-paths`를 추가하세요.
-
-`context_escrow.py`는 대용량 output을 Claude context에 그대로 넣지 않고 `.context-guard/artifacts` 아래 `0o600` 파일로 저장합니다. 저장 전에 sanitizer를 적용해 secret/path 노출을 줄이고, receipt에는 `artifact_id`, line/byte count, 줄 번호가 포함된 top-error receipt, 중복 라인 그룹, 대표 head/tail, 정제된 bounded `suggested_queries`와 `get --lines`/`get --pattern` query 예시만 출력합니다. suggested `--lines START:END` query에 `--max-lines`가 함께 있으면 이는 해당 line range의 반환 cap일 뿐 selector를 넓히는 옵션이 아닙니다. `get`과 `list`는 legacy 기본 위치인 `.claude-token-optimizer/artifacts`도 함께 읽어 리브랜딩 전 receipt를 계속 조회할 수 있습니다. 저장된 artifact는 sanitize된 사본이며, 필요할 때만 `get <artifact_id> --lines 10:40`처럼 정확한 범위를 조회하세요. 파이프라인 저장은 capture/query 용도이므로 producer 명령의 exit code가 필요한 release check에서는 shell `pipefail`/별도 `$?` 저장을 쓰거나 `trim_command_output.py -- ...`로 감싸세요.
-
-
-`context_pack.py auto`는 `suggest`와 `build`를 한 번에 합성해 build-compatible manifest와 예산 기반 Markdown pack을 함께 만듭니다. `auto --explain`은 manifest, pack 본문, receipt, byte budget을 바꾸지 않고 결정적 로컬 선택/build 이유를 JSON 또는 텍스트로 짧게 보여줍니다. JSON explain에는 bounded `repo_map`도 포함되어 sampled byte/token-proxy tree, category-only secret risk summary, signature-first hints, explain-only graph rank, 기존 `slice`/symbol 재조회 힌트를 제공합니다. 이 repo-map은 네트워크·모델 호출·임베딩 없이 로컬 표준 라이브러리 휴리스틱만 쓰며, pack 선택/본문/receipt를 바꾸지 않고 provider token 또는 savings claim으로 해석하면 안 됩니다. `context_pack.py suggest`는 `--query`, `--diff`, 반복 `--files`, 가림 처리한 `--output`, `--test-output`에서 build-compatible manifest 후보를 만듭니다. 모두 `--root` 아래 로컬 파일과 `git diff`만 읽고, 네트워크·모델 호출·임베딩·provider 비용 추정은 하지 않습니다. `context_pack.py build`는 여러 로컬 파일 source를 우선순위와 줄 범위에 따라 정렬하고, 렌더링된 UTF-8 byte budget 안에서 Markdown context pack을 만듭니다. 포함·부분 포함·누락 source, 누락 사유, `.context-guard/packs` bounded receipt, 그리고 `slice --lines` 정확 재조회 명령을 JSON으로 남깁니다. pack 본문과 receipt를 만들기 전에 sanitizer를 적용하며, token 값은 관측값이 아닌 추정 proxy로만 표시합니다.
-
-`context_filter.py`는 opt-in declarative output filter helper입니다. filter JSON은 사용자가 package code 밖(예: `.context-guard/filter-dsl.json`)에 두고 `validate`로 검증한 뒤 `run --config ... -- <command>`로 적용합니다. invalid config, no-match, filter error, empty output, protected `git`/test/lint/`gh` failure는 원래 command stdout/stderr와 exit code를 passthrough합니다. filtered mode는 stdout+stderr를 합친 line에 filter를 적용해 stdout으로 쓰고, passthrough mode는 stdout/stderr stream을 그대로 보존합니다. `--json-report`는 stdout을 command/filter output 전용으로 두기 위해 stderr에만 diagnostic JSON을 쓰지만, protected nonzero passthrough에서는 stderr 원문 보존을 위해 report를 생략합니다. token/cost 절감 수치는 측정 claim이 아니라 local presentation 변화로만 다루세요.
-
-`tool_schema_pruner.py`는 provider-neutral tool/MCP catalog helper입니다. `select`는 task query와 lexical overlap으로 top-k tool을 고르고, inline schema는 `--budget-bytes` 안에만 넣으며, compact receipt와 별도 sanitized payload를 `.context-guard/tool-prune`에 기록합니다. `get`은 payload size/SHA-256을 검증한 뒤 전체 정제 schema를 반환합니다. 이 helper는 MCP 설정을 바꾸지 않으며, token 절감은 측정값이 아니라 추정 proxy로만 표현합니다.
-
-`context_compress.py --protected-policy`는 기본 압축 동작을 바꾸지 않고 code fence, diff, identifier, numeric constant, hash, path, stack frame, quoted string, JSON key 같은 보호-zone class/count 정책 메타데이터를 추가합니다. 보호-zone 정책은 semantic/paraphrase rewrite를 금지하고 structural dedupe/window/truncate 및 artifact retrieval만 허용합니다. raw span은 receipt에 저장하지 않으며, lossy structural transform에는 정확 재조회가 필요하다는 hint를 남깁니다.
-
-`cost_guard.py compile`은 section manifest의 `protected`, `semantic_sensitive`, `protected_zone_classes`, `content_type`, `volatile`, `ttl`, `bytes` 필드를 읽어 `protected_zone_policy`와 `transform_policy`를 출력합니다. `protected=true`와 `volatile=true`가 같이 있으면 volatile이 cache ordering을 tail 쪽으로 보내고, protection은 transform/retrieval 정책만 제어합니다. 대용량 protected section은 local artifact retrieval을 권고하지만 provider prompt cache를 대체한다고 주장하지 않습니다.
-
-`experimental_registry.py` provides the `context-guard experiments` metadata surface. It is default-off and project-local: `enable`/`disable` update `.context-guard/experiments.json` only, while existing helper behavior still requires explicit flags. The registry marks the receipt-backed output trim path (`trim_command_output.py --digest markdown|json --artifact-receipt`) and protected-zone policy path (`context_compress.py --protected-policy`, plus `cost_guard.py compile` protected section metadata) as available explicit-flag experiments. It also exposes `experimental_registry.py plan context-diff-compaction` as a read-only dry-run planner and `experimental_registry.py emit context-diff-compaction --receipt-id ... --reexpand-command ...` as an explicit local runtime: `plan` summarizes diff files/hunks without replacement text, while `emit` outputs only caller-supplied compact replacement text when reviewable hunks, exact local artifact content matching the input diff, valid re-expand metadata, and a smaller replacement are present; it verifies local receipt content but still does not execute the re-expand command or claim hosted savings. `experimental_registry.py plan visual-crop-ocr` is a shipped dry-run metadata planner for full visual evidence receipts plus crop/OCR fixture notes, and `experimental_registry.py emit visual-crop-ocr` is an explicit local evidence-pack runtime for caller-supplied crop/OCR evidence. The visual lane never captures screenshots, crops images, parses screenshots, runs OCR, calls OCR/image services, writes evidence files, emits replacement evidence, or claims hosted savings. `experimental_registry.py plan learned-compression` is a deny-by-default dry-run safety checker for sanitized trusted prose plus exact fallback handles, and `experimental_registry.py emit learned-compression` is an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content. The learned lane never runs learned/synthetic compressor execution, embeddings, model calls, rerankers, subprocesses, external services, or generated replacement text, and it never claims hosted savings. `experimental_registry.py plan self-hosted-metrics-ledger` is a dry-run preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost sidecar evidence; the dry-run preview does not write a ledger. `experimental_registry.py record self-hosted-metrics-ledger --ledger-jsonl ...` explicitly writes one local JSONL sidecar row and still never turns self-hosted telemetry into hosted API token/cost savings claims. `experimental_registry.py plan local-proxy` is a localhost-only dry-run advisory plan, `experimental_registry.py plan local-proxy-external-forwarding` is a design-only dry-run gate for future external forwarding that requires explicit intent, HTTPS allowlist, threat model notes, credential redaction policy, and provider-evidence boundary while performing no DNS lookup, external service call, or traffic forwarding, `experimental_registry.py record local-proxy-runtime-gate --ledger-jsonl ...` is an explicit local gate-row runtime that starts no listener, forwards no traffic, and performs no DNS lookup, and `experimental_registry.py serve local-proxy` is an explicit one-shot loopback forwarding MVP: it requires `--runtime-gate-ack --forwarding-gate-ack --once`, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it persists no API keys, supports no external forwarding or CONNECT/TLS proxying, and makes no hosted savings claim. Optional `--diagnostic-ledger-jsonl` appends one shifted-cost diagnostic row only after a successful forwarded request, without raw headers/bodies or hosted-savings evidence. External proxy forwarding runtime remains non-shipped. Other roadmap lanes remain advisory until separate runtime gates exist.
-
-`benchmark_runner.py`는 `research/benchmark-plan.md`의 고정 task/variant 실험을 실행합니다. `variant_prompt_files`는 선택된 task/variant를 필터링한 뒤 필요한 file-backed prompt만 읽으므로 선택하지 않은 fixture의 누락 파일이 선택된 실행을 깨지 않습니다. `--ledger-jsonl`은 subagent·artifact 등 외부 실행 표면으로 옮겨간 token/cost와 run별 측정 가능 여부를 남기고, 선택적 `self_hosted_metrics` provider payload는 run별 sidecar로만 기록합니다. `--report-json`은 baseline 대비 실제 token/cost 절감과 proxy byte 감소를 분리한 A/B report를 생성하며, `self_hosted_metrics`는 CSV/report 요약에 접지 않습니다. Report의 `matched_pair_evidence`는 성공한 baseline/variant task bucket을 transform, quality gate, 측정 가능 여부, claim boundary와 연결하므로 절감 주장을 쓰기 전에 이 항목을 확인하세요.
-
-`../research/experimental-token-reduction-radar.md`는 learned compression, generated crop/OCR/visual-token pruning, self-hosted KV/latent inference optimization 같은 선택적 미래 실험을 문서화한 gate입니다. `../docs/experimental-benchmark-fixtures.md`에는 fixture-only task/variant 시작 예시가 있습니다. 이 radar와 fixture는 hosted API token/cost 절감을 보장하지 않습니다. 현재 제공되는 helper surface는 명시적 local context-diff emit, visual evidence-pack emit, learned candidate emit, self-hosted metrics record, local proxy gate record, one-shot literal-loopback local proxy serve, design-only external-forwarding plan 같은 좁은 local surface뿐이며, hosted API token/cost 절감 주장은 provider가 측정한 matched-task 근거가 있을 때만 허용합니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader external/daemon/hostname-DNS/credential-bearing local proxy forwarding constraints를 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 유지합니다.
-
-`claude_transcript_cost_audit.py --recommend`의 기본 출력은 공유 시 안전하도록 transcript 경로를 `basename#hash`, 명령을 `command#hash` 형태로 익명화합니다. 로컬 원문 식별자가 꼭 필요할 때만 `--show-paths` 또는 `--show-commands`를 추가하세요.
-대용량/손상 transcript 방어를 위해 파일 단위 `--max-file-bytes`, JSONL record 단위 `--max-line-bytes` 제한도 기본 적용되며, 건너뛴 항목은 skip count와 warning으로 표시됩니다. JSON summary/feasibility 출력의 `cache_friendliness`는 제한된 정제 segment hash로 안정적인 prefix와 volatile prefix/tail 신호를 비교하는 휴리스틱입니다. `cache_layout_advice`는 그 신호를 긴 세션 분리, prefix 안정화, diet 점검 같은 순위화된 확인/실험으로 연결하지만, 관측 issue와 가설/입증 cause를 분리합니다. `--feasibility-json`은 macOS-visible prototype 같은 consumer가 안정적인 top-level field에만 바인딩하도록 `mac_visibility` 계약도 함께 제공합니다. 원문 prompt text는 출력하지 않고, provider cache token field와 historical token total은 ContextGuard가 만든 토큰 절감 또는 live headroom 증거가 아니라 별도 진단 텔레메트리로 해석하세요.
-
-`context_guard_diet.py scan`은 항상 로컬에서만 읽는 read-only 스캐너입니다. 기본 출력은 project root를 익명화하고 상대경로 중심으로 보고합니다. `--top`은 보고서의 context-like file 목록과 context-exclusion recommendation 목록에 공통으로 적용됩니다. `--show-paths`는 로컬/비공개 디버깅에서만 쓰세요.
-
-`context_guard_diet.py structural-waste`는 opt-in read-only 구조 진단입니다. context/rule file의 중복 rule unit, stale Python import 후보, unused skill 후보, MCP/tool schema 과다, local JSON/JSONL log의 반복 file read·중복 tool call을 bounded scan으로 보고합니다. 네트워크 호출이나 삭제/수정은 하지 않고, 기본 출력은 raw prompt/tool input/command를 출력하지 않으며 secret-shaped path component를 redaction합니다. import/skill 결과는 동적 사용을 놓칠 수 있는 advisory 후보로만 다루세요.
-
-`context_pack.py suggest`가 쓰는 manifest는 그대로 `context_pack.py build --manifest suggested-pack.json`에 넣을 수 있습니다. `context_pack.py build`의 retrieval command는 path/root를 안전하게 표시할 수 있을 때만 출력됩니다. 안전하지 않으면 pack 본문과 JSON source metadata에 `retrieval_omitted_reason`을 기록합니다. `token_proxy`는 렌더링된 pack 문자 수를 `chars_div_4`로 나눈 추정치이며, provider가 실제로 청구/소모한 token 측정값이 아닙니다.
-
-`setup_wizard.py`는 설치 후 한 번 실행하는 설정 마법사입니다. 터미널에서 실행하면 deny rules, statusline, Bash trim/sanitize hook, large Read guard, 반복 실패 nudge, model/effort defaults를 project-local `.claude/settings.json`에 병합합니다. 비대화형 환경에서는 `--verify`로 읽기 전용 상태 점검을 하고, `--plan`으로 미리 본 뒤, `--yes`로 추천값을 적용하세요. Codex/Gemini/Cursor 같은 rule-file 에이전트에는 `--brief-mode lite|standard|ultra`로 권고 brief 스니펫을 설치·교체하고, `--brief-mode off`로 제거할 수 있습니다. 설정을 적용하면 read-only `context_guard_diet.py scan` 요약을 자동으로 출력해 남은 gap을 확인할 수 있습니다. 반복 실패 nudge가 방해되는 프로젝트는 `--no-failed-attempt-nudge`로, post-setup scan이 불필요한 자동화는 `--no-diet-scan`으로 제외할 수 있습니다.
-
-`guard_large_read.py`는 opt-in Read hook입니다. 큰 파일 전체를 Claude context에 넣기 전에 progressive read ladder를 반환해 `rg -n` 검색, `read_symbol.py` symbol slice, 작은 `offset`/`limit` Read 순서로 좁히게 합니다. Python/JS/TS/Go/Rust/Markdown 파일은 bounded prefix에서 top-level outline과 line estimate도 함께 보여줍니다. 같은 oversized file fingerprint를 반복해서 읽으려 하면 repeated-read dedup 힌트를 추가해 이전 ladder를 재사용하게 합니다. `CONTEXT_GUARD_READ_GUARD=0`으로 로컬에서 일시 비활성화할 수 있습니다.
-
-`failed_attempt_nudge.py`는 같은 Bash 실패 방향이 두 번 반복되면 `/clear`/`/compact` 힌트를 주고, 세 번 이상 반복되면 strategy-switch signal을 추가해 동일 명령 재시도 대신 다른 가설·더 작은 재현·수정 후 재검증으로 전환하게 합니다. recommended setup에서는 기본으로 켜지며, 실행을 막지 않고 짧은 추가 컨텍스트만 주입합니다.
-
-`sanitize_output.py`는 grep/diff output을 Claude에게 보여주기 전에 secret-like line, Authorization header, private key block, API token, credential URL을 `[REDACTED]`로 바꾸고, 긴 결과는 head / grep·diff·security anchor / tail만 남깁니다. 명령을 감싸는 wrapper mode는 원래 종료 코드를 보존합니다. stdin pipe도 지원하지만 producer exit code는 shell `pipefail` 없이는 알 수 없으므로 자동화에는 `python3 .../sanitize_output.py -- rg ...`처럼 wrapper mode를 선호하세요. 절대경로는 기본 익명화되고 로컬 디버깅에서만 `--show-paths`를 쓰세요. `rewrite_bash_for_token_budget.py` hook은 단일 argv 형태의 `rg`, `grep`, `git grep`, `git diff`, `git show`, `git log -p`를 자동으로 이 sanitizer에 감쌉니다.
-
-Claude Code에 적용하려면 `settings.example.json`을 `.claude/settings.json`으로 복사하되, 먼저 작은 repo에서 quoting/종료 코드를 확인하세요.
-
-
-## License
-
-Copyright 2026 jinhongan. Licensed under the Apache License 2.0. See the repository [LICENSE](../LICENSE) and [NOTICE](../NOTICE).