@ictechgy/context-guard 0.4.9 → 0.4.11

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,15 +23,26 @@ 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
+NO_FOLLOW_SUPPORTED = hasattr(os, "O_NOFOLLOW")
+DIR_FD_OPEN_SUPPORTED = bool(os.supports_dir_fd and os.open in os.supports_dir_fd)
+DIR_FD_MKDIR_SUPPORTED = bool(os.supports_dir_fd and os.mkdir in os.supports_dir_fd)
+DIR_FD_STAT_SUPPORTED = bool(os.supports_dir_fd and os.stat in os.supports_dir_fd)
+DIR_FD_UNLINK_SUPPORTED = bool(os.supports_dir_fd and os.unlink in os.supports_dir_fd)
 MAX_DESCRIPTION_CHARS = 360
 MAX_OMITTED_TOOLS = 30
 TOKEN_PROXY_CHARS_PER_TOKEN = 4
@@ -94,13 +105,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:
@@ -191,12 +206,26 @@ def sanitize_value(value: Any, *, sensitive_context: bool = False, sensitive_sch
 
 
 def read_limited_path(path: Path, max_bytes: int) -> str:
+    if not NO_FOLLOW_SUPPORTED:
+        fail("catalog reads require O_NOFOLLOW support")
+    reject_parent_traversal(path, label="catalog")
+    # Preserve clear diagnostics for stable symlink paths, then anchor the real
+    # read to an opened no-follow parent fd so parent/leaf swaps after this
+    # precheck still fail closed.
     reject_symlink_components(path)
-    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    parent_fd = open_private_directory_no_follow(path.parent, label="catalog directory", create=False)
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    leaf = path.name
+    if leaf in {"", ".", ".."}:
+        os.close(parent_fd)
+        fail("catalog must name a regular file")
     try:
-        fd = os.open(str(path), flags)
+        fd = os.open(leaf, flags, dir_fd=parent_fd)
     except OSError as exc:
-        fail(f"catalog read failed: {exc}")
+        os.close(parent_fd)
+        fail(f"catalog read failed: {os_error_detail(exc)}")
     try:
         st = os.fstat(fd)
         if not stat.S_ISREG(st.st_mode):
@@ -206,6 +235,7 @@ def read_limited_path(path: Path, max_bytes: int) -> str:
         data = os.read(fd, max_bytes + 1)
     finally:
         os.close(fd)
+        os.close(parent_fd)
     if len(data) > max_bytes:
         fail(f"catalog exceeds --max-catalog-bytes: > {max_bytes}")
     return data.decode("utf-8", errors="replace")
@@ -399,15 +429,142 @@ def reject_symlink_components(path: Path) -> None:
             fail(f"refusing path through non-directory component: {current}")
 
 
+def dir_fd_replace_supported() -> bool:
+    try:
+        import inspect
+
+        signature = inspect.signature(os.replace)
+    except (TypeError, ValueError):
+        return True
+    return "src_dir_fd" in signature.parameters and "dst_dir_fd" in signature.parameters
+
+
+DIR_FD_REPLACE_SUPPORTED = dir_fd_replace_supported()
+
+
+def reject_parent_traversal(path: Path, *, label: str) -> None:
+    if ".." in path.parts:
+        fail(f"{label} must not contain parent traversal")
+
+
+def os_error_detail(exc: OSError) -> str:
+    detail = exc.strerror or str(exc) or exc.__class__.__name__
+    if exc.errno is not None:
+        return f"{detail} (errno {exc.errno})"
+    return detail
+
+
+def no_follow_dir_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        fail("private store IO requires O_NOFOLLOW support")
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    return flags
+
+
+def private_temp_file_flags() -> int:
+    if not NO_FOLLOW_SUPPORTED:
+        fail("private store IO requires O_NOFOLLOW support")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
+def open_private_directory_no_follow(path: Path, *, label: str, create: bool) -> int:
+    reject_parent_traversal(path, label=label)
+    path = normalize_allowed_first_absolute_symlink(path.expanduser())
+    if not DIR_FD_OPEN_SUPPORTED:
+        fail(f"{label} requires dir_fd open support")
+    if create and not DIR_FD_MKDIR_SUPPORTED:
+        fail(f"{label} requires dir_fd mkdir support")
+    flags = no_follow_dir_flags()
+    if path.is_absolute():
+        root_flags = os.O_RDONLY | (os.O_CLOEXEC if hasattr(os, "O_CLOEXEC") else 0)
+        current_fd = os.open(path.anchor or os.sep, root_flags)
+        parts = path.parts[1:]
+    else:
+        current_fd = os.open(".", flags)
+        parts = path.parts
+    try:
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                fail(f"{label} must not contain parent traversal")
+            try:
+                next_fd = os.open(part, flags, dir_fd=current_fd)
+            except FileNotFoundError:
+                if not create:
+                    raise
+                os.mkdir(part, 0o700, dir_fd=current_fd)
+                next_fd = os.open(part, flags, dir_fd=current_fd)
+            try:
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    fail(f"{label} must not traverse non-directory components")
+            except Exception:
+                os.close(next_fd)
+                raise
+            os.close(current_fd)
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    except OSError as exc:
+        fail(f"could not inspect {label}: {os_error_detail(exc)}")
+    finally:
+        if current_fd >= 0:
+            os.close(current_fd)
+
+
+def precheck_private_leaf(parent_fd: int, leaf: str, *, label: str) -> None:
+    if not DIR_FD_STAT_SUPPORTED:
+        fail(f"{label} requires dir_fd stat support")
+    try:
+        st = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    except OSError as exc:
+        fail(f"could not inspect {label}: {os_error_detail(exc)}")
+    if not stat.S_ISREG(st.st_mode):
+        fail(f"{label} must be missing or a regular file")
+
+
+def write_all_fd(fd: int, data: bytes) -> None:
+    view = memoryview(data)
+    offset = 0
+    while offset < len(view):
+        written = os.write(fd, view[offset:])
+        if written <= 0:
+            raise OSError("short write")
+        offset += written
+
+
+def fsync_best_effort(fd: int) -> None:
+    try:
+        os.fsync(fd)
+    except OSError:
+        pass
+
+
 def ensure_private_dir(path: Path) -> None:
-    path = normalize_allowed_first_absolute_symlink(path)
-    reject_symlink_components(path)
+    reject_parent_traversal(path, label="store directory")
     try:
-        path.mkdir(parents=True, exist_ok=True)
-        reject_symlink_components(path)
-        os.chmod(path, 0o700)
+        fd = open_private_directory_no_follow(path, label="store directory", create=True)
     except OSError as exc:
         fail(f"store directory unavailable: {exc}")
+    try:
+        try:
+            os.fchmod(fd, 0o700)
+        except OSError:
+            pass
+    finally:
+        os.close(fd)
 
 
 def write_private_json_atomic(path: Path, data: dict[str, Any], *, max_bytes: int, label: str) -> int:
@@ -415,43 +572,77 @@ def write_private_json_atomic(path: Path, data: dict[str, Any], *, max_bytes: in
     size = byte_len_text(text)
     if size > max_bytes:
         fail(f"{label} exceeds size cap: {size} > {max_bytes}")
-    ensure_private_dir(path.parent)
-    tmp = path.with_name(path.name + f".tmp-{os.getpid()}-{time.time_ns()}")
-    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
+    reject_parent_traversal(path, label=label)
+    if not DIR_FD_REPLACE_SUPPORTED:
+        fail(f"{label} write requires dir_fd replace support")
+    if not DIR_FD_UNLINK_SUPPORTED:
+        fail(f"{label} write requires dir_fd unlink support")
+    if not DIR_FD_STAT_SUPPORTED:
+        fail(f"{label} write requires dir_fd stat support")
+    parent_fd = open_private_directory_no_follow(path.parent, label="store directory", create=True)
+    fd = -1
+    temp_leaf: str | None = None
     try:
-        fd = os.open(str(tmp), flags, 0o600)
-    except OSError as exc:
-        fail(f"{label} write failed: {exc}")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
-            handle.write(text)
-            handle.flush()
-            try:
-                os.fsync(handle.fileno())
-            except OSError:
-                pass
-        os.replace(tmp, path)
         try:
-            os.chmod(path, 0o600)
+            os.fchmod(parent_fd, 0o700)
         except OSError:
             pass
+        leaf = path.name
+        if leaf in {"", ".", ".."}:
+            fail(f"{label} must name a regular file")
+        precheck_private_leaf(parent_fd, leaf, label=label)
+        for _attempt in range(20):
+            candidate = f".{leaf}.{os.getpid()}.{time.time_ns()}.tmp"
+            try:
+                fd = os.open(candidate, private_temp_file_flags(), 0o600, dir_fd=parent_fd)
+                temp_leaf = candidate
+                break
+            except FileExistsError:
+                continue
+        if fd < 0 or temp_leaf is None:
+            fail(f"{label} write failed: could not create temporary file")
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            fail(f"{label} temporary file must be a regular file")
+        os.fchmod(fd, 0o600)
+        write_all_fd(fd, text.encode("utf-8"))
+        fsync_best_effort(fd)
+        os.close(fd)
+        fd = -1
+        fsync_best_effort(parent_fd)
+        os.replace(temp_leaf, leaf, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)
+        temp_leaf = None
+        fsync_best_effort(parent_fd)
+    except OSError as exc:
+        fail(f"{label} write failed: {os_error_detail(exc)}")
     except Exception:
-        try:
-            tmp.unlink()
-        except OSError:
-            pass
         raise
+    finally:
+        if fd >= 0:
+            os.close(fd)
+        if temp_leaf is not None:
+            try:
+                os.unlink(temp_leaf, dir_fd=parent_fd)
+            except OSError:
+                pass
+        os.close(parent_fd)
     return size
 
 
 def read_private_text(path: Path, *, max_bytes: int, label: str) -> tuple[str, int]:
-    if path.is_symlink():
-        fail(f"{label} must not be a symlink")
-    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    reject_parent_traversal(path, label=label)
+    parent_fd = open_private_directory_no_follow(path.parent, label=f"{label} directory", create=False)
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    leaf = path.name
+    if leaf in {"", ".", ".."}:
+        os.close(parent_fd)
+        fail(f"{label} must name a regular file")
     try:
-        fd = os.open(str(path), flags)
+        fd = os.open(leaf, flags, dir_fd=parent_fd)
     except OSError as exc:
-        fail(f"{label} read failed: {exc}")
+        os.close(parent_fd)
+        fail(f"{label} read failed: {os_error_detail(exc)}")
     try:
         st = os.fstat(fd)
         if not stat.S_ISREG(st.st_mode):
@@ -461,32 +652,16 @@ def read_private_text(path: Path, *, max_bytes: int, label: str) -> tuple[str, i
         data = os.read(fd, max_bytes + 1)
     finally:
         os.close(fd)
+        os.close(parent_fd)
     if len(data) > max_bytes:
         fail(f"{label} exceeds trusted size cap: > {max_bytes}")
     return data.decode("utf-8", errors="replace"), len(data)
 
 
 def read_private_json(path: Path, *, max_bytes: int, label: str) -> dict[str, Any]:
-    if path.is_symlink():
-        fail(f"{label} must not be a symlink")
-    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    text, _size = read_private_text(path, max_bytes=max_bytes, label=label)
     try:
-        fd = os.open(str(path), flags)
-    except OSError as exc:
-        fail(f"{label} read failed: {exc}")
-    try:
-        st = os.fstat(fd)
-        if not stat.S_ISREG(st.st_mode):
-            fail(f"{label} must be a regular file")
-        if st.st_size > max_bytes:
-            fail(f"{label} exceeds trusted size cap: {st.st_size} > {max_bytes}")
-        data = os.read(fd, max_bytes + 1)
-    finally:
-        os.close(fd)
-    if len(data) > max_bytes:
-        fail(f"{label} exceeds trusted size cap: > {max_bytes}")
-    try:
-        parsed = json.loads(data.decode("utf-8", errors="replace"))
+        parsed = json.loads(text)
     except json.JSONDecodeError as exc:
         fail(f"{label} is malformed JSON: {exc.msg}")
     if not isinstance(parsed, dict):
@@ -583,6 +758,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 +846,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 +955,160 @@ 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)
+    listed_deferred_schema_bytes = sum(byte_len_json(cand.schema) for cand in deferred_candidates)
+    total_deferred_schema_bytes = sum(byte_len_json(cand.schema) for cand in ranked[core_top:])
+    tool_stub_report_bytes = byte_len_json(core_tools) + byte_len_json(deferred_tools)
+    all_schema_tokens = proxy_tokens(all_schema_bytes)
+    inline_core_schema_tokens = proxy_tokens(core_schema_bytes)
+    listed_deferred_schema_tokens = proxy_tokens(listed_deferred_schema_bytes)
+    total_deferred_schema_tokens = proxy_tokens(total_deferred_schema_bytes)
+    tool_stub_report_tokens = proxy_tokens(tool_stub_report_bytes)
+    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,
+        "deferred_schema_retrieval_required_before_use": True,
+        "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,
+            "inline_core_schema_bytes": core_schema_bytes,
+            "listed_deferred_schema_bytes": listed_deferred_schema_bytes,
+            "total_deferred_schema_bytes": total_deferred_schema_bytes,
+            "tool_stub_report_bytes": tool_stub_report_bytes,
+            "all_schema_tokens_estimated": all_schema_tokens,
+            "inline_core_schema_tokens_estimated": inline_core_schema_tokens,
+            "listed_deferred_schema_tokens_estimated": listed_deferred_schema_tokens,
+            "total_deferred_schema_tokens_estimated": total_deferred_schema_tokens,
+            "tool_stub_report_tokens_estimated": tool_stub_report_tokens,
+            "gross_listed_deferred_schema_tokens_avoided": listed_deferred_schema_tokens,
+            "gross_total_deferred_schema_tokens_avoided": total_deferred_schema_tokens,
+            "net_initial_report_tokens_delta": tool_stub_report_tokens - all_schema_tokens,
+            "net_initial_report_tokens_delta_semantics": "tool_stub_report_tokens_estimated_minus_all_schema_tokens_estimated",
+            "estimated_initial_schema_tokens_avoided": max(0, all_schema_tokens - tool_stub_report_tokens),
+            "estimated_initial_schema_tokens_avoided_semantics": "max(0, all_schema_tokens_estimated - tool_stub_report_tokens_estimated)",
+            "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,
+            "deferred_schema_retrieval_required_before_use": 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.",
+            "Deferred schema token fields are initial-prompt proxy accounting; full schemas must be retrieved before deferred tool use.",
+            "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 +1213,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 +1245,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