@ictechgy/context-guard 0.4.0

package/context-guard-kit/tool_schema_pruner.py

@@ -0,0 +1,837 @@
+#!/usr/bin/env python3
+"""Select a bounded top-k subset from a local tool/MCP schema catalog.
+
+The helper is advisory only: it never edits MCP config or an agent's tool
+registry.  It writes a compact receipt plus a separate sanitized payload so an
+agent can inject a small selection report first and recover the full sanitized
+schema later when needed.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import shlex
+from pathlib import Path
+import re
+import stat
+import sys
+import time
+from dataclasses import dataclass
+from typing import Any, NoReturn
+
+TOOL_NAME = "context-guard-tool-prune"
+SCHEMA_VERSION = "contextguard.tool-prune.v1"
+DEFAULT_STORE_DIR = ".context-guard/tool-prune"
+DEFAULT_TOP = 5
+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_LABEL_CHARS = 160
+MAX_DESCRIPTION_CHARS = 360
+MAX_OMITTED_TOOLS = 30
+TOKEN_PROXY_CHARS_PER_TOKEN = 4
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
+RECEIPT_ID_RE = re.compile(r"^[a-f0-9]{16,64}$")
+TERM_RE = re.compile(r"[A-Za-z0-9_]+")
+SECRET_RE = re.compile(
+    r"(?is)("
+    r"-----BEGIN (?:[A-Z0-9 ]*PRIVATE KEY|PGP PRIVATE KEY BLOCK)-----.*?-----END (?:[A-Z0-9 ]*PRIVATE KEY|PGP PRIVATE KEY BLOCK)-----|"
+    r"AKIA[0-9A-Z]{16}|"
+    r"gh[pousr]_[A-Za-z0-9_]{20,}|"
+    r"github_pat_[A-Za-z0-9_]{20,}|"
+    r"glpat-[A-Za-z0-9_-]{12,}|"
+    r"xox[abprs]-[A-Za-z0-9-]{10,}|"
+    r"sk-(?:ant|proj)-[A-Za-z0-9_-]{8,}|"
+    r"sk-[A-Za-z0-9][A-Za-z0-9_-]{20,}|"
+    r"AIza[0-9A-Za-z_\-]{20,}|"
+    r"(?i:Authorization)\s*:\s*(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+|"
+    r"[?&](?:X-Amz-Signature|X-Amz-Credential|X-Amz-Security-Token|AWSAccessKeyId|Signature|sig|access_token|refresh_token|id_token|auth|authorization|api[_-]?key|apikey|token|secret|password|client[_-]?secret|private[_-]?key|privatekey|pgp[_-]?private[_-]?key|pgpprivatekey|ssh[_-]?key|sshkey|(?:aws[_-]?)?access[_-]?key(?:[_-]?id)?|awsaccesskeyid)=[^&#\s,}\]]+|"
+    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)$")
+
+
+class ToolPruneError(ValueError):
+    """User-facing fail-closed error."""
+
+
+@dataclass(frozen=True)
+class Candidate:
+    name: str
+    server: str | None
+    description: str
+    schema: dict[str, Any]
+    index: int
+    score: float = 0.0
+    rank: int = 0
+
+
+def fail(message: str) -> NoReturn:
+    raise ToolPruneError(message)
+
+
+def byte_len_text(text: str) -> int:
+    return len(text.encode("utf-8", errors="replace"))
+
+
+def json_bytes(data: Any, *, indent: int | None = None) -> str:
+    return json.dumps(data, ensure_ascii=False, sort_keys=True, separators=(",", ":") if indent is None else None, indent=indent)
+
+
+def byte_len_json(data: Any) -> int:
+    return byte_len_text(json_bytes(data))
+
+
+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)
+    except (TypeError, ValueError, OverflowError):
+        fail(f"{name} must be an integer")
+    if number < minimum:
+        fail(f"{name} must be >= {minimum}")
+    if number > maximum:
+        fail(f"{name} must be <= {maximum}")
+    return number
+
+
+def cap_text(value: object, limit: int = MAX_LABEL_CHARS) -> str:
+    text = " ".join(str(value or "").split())
+    if len(text) <= limit:
+        return text
+    marker = f"…[trimmed:{len(text)} chars]"
+    return text[: max(0, limit - len(marker))] + marker
+
+
+def redact_string(value: str) -> tuple[str, int]:
+    def repl(match: re.Match[str]) -> str:
+        text = match.group(0)
+        if "=" in text:
+            key = text.split("=", 1)[0]
+            if SENSITIVE_KEY_RE.search(key):
+                return key + "=[REDACTED]"
+        if ":" in text:
+            key = text.split(":", 1)[0]
+            if SENSITIVE_KEY_RE.search(key):
+                return key + ": [REDACTED]"
+        return "[REDACTED]"
+
+    return SECRET_RE.subn(repl, value)
+
+
+def redact_whole_value(value: Any) -> tuple[Any, int]:
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        count = 0
+        for key, item in value.items():
+            safe_key, key_redactions = redact_string(str(key))
+            sanitized, item_redactions = redact_whole_value(item)
+            out[safe_key] = sanitized
+            count += key_redactions + item_redactions
+        return out, count
+    if isinstance(value, list):
+        out: list[Any] = []
+        count = 0
+        for item in value:
+            sanitized, item_redactions = redact_whole_value(item)
+            out.append(sanitized)
+            count += item_redactions
+        return out, count
+    return "[REDACTED]", 1
+
+
+def sanitize_value(value: Any, *, sensitive_context: bool = False, sensitive_schema_context: bool = False) -> tuple[Any, int]:
+    if sensitive_context:
+        return redact_whole_value(value)
+    if isinstance(value, str):
+        return redact_string(value)
+    if isinstance(value, list):
+        out: list[Any] = []
+        count = 0
+        for item in value:
+            sanitized, redactions = sanitize_value(item, sensitive_schema_context=sensitive_schema_context)
+            out.append(sanitized)
+            count += redactions
+        return out, count
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        count = 0
+        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))
+            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)
+            elif key_sensitive:
+                sanitized, item_redactions = sanitize_value(item, sensitive_schema_context=True)
+            elif sensitive_schema_context and value_bearing:
+                sanitized, item_redactions = sanitize_value(item, sensitive_context=True)
+            else:
+                sanitized, item_redactions = sanitize_value(item, sensitive_schema_context=sensitive_schema_context)
+            out[safe_key] = sanitized
+            count += key_redactions + item_redactions
+        return out, count
+    return value, 0
+
+
+def read_limited_path(path: Path, max_bytes: int) -> str:
+    reject_symlink_components(path)
+    flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
+    try:
+        fd = os.open(str(path), flags)
+    except OSError as exc:
+        fail(f"catalog read failed: {exc}")
+    try:
+        st = os.fstat(fd)
+        if not stat.S_ISREG(st.st_mode):
+            fail("catalog must be a regular file")
+        if st.st_size > max_bytes:
+            fail(f"catalog exceeds --max-catalog-bytes: {st.st_size} > {max_bytes}")
+        data = os.read(fd, max_bytes + 1)
+    finally:
+        os.close(fd)
+    if len(data) > max_bytes:
+        fail(f"catalog exceeds --max-catalog-bytes: > {max_bytes}")
+    return data.decode("utf-8", errors="replace")
+
+
+def read_limited_stdin(max_bytes: int) -> str:
+    data = sys.stdin.buffer.read(max_bytes + 1)
+    if len(data) > max_bytes:
+        fail(f"catalog exceeds --max-catalog-bytes: > {max_bytes}")
+    return data.decode("utf-8", errors="replace")
+
+
+def parse_catalog_text(text: str) -> tuple[Any, int]:
+    try:
+        raw = json.loads(text)
+    except json.JSONDecodeError as exc:
+        fail(f"catalog must be valid JSON: {exc.msg}")
+    return sanitize_value(raw)
+
+
+def first_str(mapping: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for key in keys:
+        value = mapping.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+def tool_schema_from_dict(raw: dict[str, Any], *, fallback_name: str | None = None, server: str | None = None, index: int = 0) -> Candidate | None:
+    name = first_str(raw, ("name", "tool", "id", "title")) or (fallback_name or "")
+    name = cap_text(name, MAX_LABEL_CHARS)
+    if not name:
+        return None
+    description = cap_text(first_str(raw, ("description", "summary", "doc", "docs")), MAX_DESCRIPTION_CHARS)
+    schema = dict(raw)
+    schema.setdefault("name", name)
+    if description and "description" not in schema:
+        schema["description"] = description
+    if server and "server" not in schema:
+        schema["server"] = server
+    return Candidate(name=name, server=cap_text(server, MAX_LABEL_CHARS) if server else None, description=description, schema=schema, index=index)
+
+
+def normalize_catalog(raw: Any) -> list[Candidate]:
+    candidates: list[Candidate] = []
+
+    def add_tool(tool: Any, *, server: str | None = None, fallback_name: str | None = None) -> None:
+        if isinstance(tool, str):
+            tool = {"name": tool}
+        if not isinstance(tool, dict):
+            return
+        cand = tool_schema_from_dict(tool, fallback_name=fallback_name, server=server, index=len(candidates))
+        if cand is not None:
+            candidates.append(cand)
+
+    def add_tools(tools: Any, *, server: str | None = None) -> None:
+        if isinstance(tools, list):
+            for tool in tools:
+                add_tool(tool, server=server)
+        elif isinstance(tools, dict):
+            for name, schema in tools.items():
+                if isinstance(schema, dict):
+                    add_tool(schema, server=server, fallback_name=str(name))
+                else:
+                    add_tool({"name": str(name), "schema": schema}, server=server)
+
+    if isinstance(raw, list):
+        add_tools(raw)
+    elif isinstance(raw, dict):
+        if "tools" in raw:
+            add_tools(raw.get("tools"), server=first_str(raw, ("server", "name")) or None)
+        if "servers" in raw and isinstance(raw.get("servers"), list):
+            for server_obj in raw.get("servers") or []:
+                if isinstance(server_obj, dict):
+                    add_tools(server_obj.get("tools"), server=first_str(server_obj, ("name", "id", "server")) or None)
+        if "mcpServers" in raw and isinstance(raw.get("mcpServers"), dict):
+            for server_name, server_obj in (raw.get("mcpServers") or {}).items():
+                if isinstance(server_obj, dict):
+                    add_tools(server_obj.get("tools"), server=str(server_name))
+        if not candidates:
+            # Simple name-to-schema map.
+            for name, schema in raw.items():
+                if name in {"tools", "servers", "mcpServers"}:
+                    continue
+                if isinstance(schema, dict):
+                    add_tool(schema, fallback_name=str(name))
+                elif isinstance(schema, (str, list)):
+                    add_tool({"name": str(name), "schema": schema})
+    if not candidates:
+        fail("catalog contains no tools")
+    return candidates
+
+
+def terms(text: str) -> set[str]:
+    return {term.lower() for term in TERM_RE.findall(text or "") if term}
+
+
+def collect_parameter_text(value: Any, *, depth: int = 0, max_items: int = 500) -> list[str]:
+    out: list[str] = []
+    if depth > 8 or max_items <= 0:
+        return out
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if len(out) >= max_items:
+                break
+            key_text = str(key)
+            if key_text.lower() in {"properties", "parameters", "inputschema", "input_schema", "schema", "description", "title", "name"}:
+                out.append(key_text)
+            elif isinstance(item, (str, int, float, bool)):
+                out.append(key_text)
+            if isinstance(item, str) and key_text.lower() in {"description", "title", "name"}:
+                out.append(item)
+            out.extend(collect_parameter_text(item, depth=depth + 1, max_items=max_items - len(out)))
+    elif isinstance(value, list):
+        for item in value[:max_items]:
+            if len(out) >= max_items:
+                break
+            out.extend(collect_parameter_text(item, depth=depth + 1, max_items=max_items - len(out)))
+    return out[:max_items]
+
+
+def score_candidate(candidate: Candidate, query_terms: set[str]) -> float:
+    if not query_terms:
+        return 0.0
+    name_terms = terms(candidate.name)
+    desc_terms = terms(candidate.description)
+    parameter_terms = terms(" ".join(collect_parameter_text(candidate.schema)))
+    score = 0.0
+    score += 4.0 * len(query_terms & name_terms)
+    score += 1.5 * len(query_terms & desc_terms)
+    score += 1.0 * len(query_terms & parameter_terms)
+    # Light substring bonus for names such as git_status when the query says status.
+    lowered_name = candidate.name.lower()
+    for term in query_terms:
+        if term and term in lowered_name and term not in name_terms:
+            score += 1.0
+    return score
+
+
+def rank_candidates(candidates: list[Candidate], query: str) -> list[Candidate]:
+    query_terms = terms(query)
+    scored: list[Candidate] = []
+    for cand in candidates:
+        scored.append(Candidate(cand.name, cand.server, cand.description, cand.schema, cand.index, score_candidate(cand, query_terms), 0))
+    scored.sort(key=lambda item: (-item.score, item.index))
+    ranked: list[Candidate] = []
+    for rank, cand in enumerate(scored, start=1):
+        ranked.append(Candidate(cand.name, cand.server, cand.description, cand.schema, cand.index, cand.score, rank))
+    return ranked
+
+
+def normalized_link_target(parent: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if not target.is_absolute():
+        target = parent / target
+    return Path(os.path.normpath(str(target)))
+
+
+def normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    if not path.is_absolute() or len(path.parts) < 2:
+        return path
+    first = path.parts[1]
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(first)
+    if expected is None:
+        return path
+    link = Path(path.anchor) / first
+    try:
+        if not stat.S_ISLNK(os.lstat(link).st_mode):
+            return path
+        if normalized_link_target(Path(path.anchor), os.readlink(link)) != expected:
+            return path
+    except OSError:
+        return path
+    return expected.joinpath(*path.parts[2:])
+
+
+def reject_symlink_components(path: Path) -> None:
+    path = normalize_allowed_first_absolute_symlink(path)
+    current = Path(path.anchor) if path.is_absolute() else Path()
+    for part in path.parts:
+        if path.is_absolute() and part == path.anchor:
+            continue
+        current = current / part
+        try:
+            st = os.lstat(current)
+        except FileNotFoundError:
+            return
+        if stat.S_ISLNK(st.st_mode):
+            fail(f"refusing path with symlink component: {current}")
+        if not stat.S_ISDIR(st.st_mode) and current != path:
+            fail(f"refusing path through non-directory component: {current}")
+
+
+def ensure_private_dir(path: Path) -> None:
+    path = normalize_allowed_first_absolute_symlink(path)
+    reject_symlink_components(path)
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+        reject_symlink_components(path)
+        os.chmod(path, 0o700)
+    except OSError as exc:
+        fail(f"store directory unavailable: {exc}")
+
+
+def write_private_json_atomic(path: Path, data: dict[str, Any], *, max_bytes: int, label: str) -> int:
+    text = json_bytes(data, indent=2) + "\n"
+    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)
+    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)
+        except OSError:
+            pass
+    except Exception:
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+    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)
+    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}")
+    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)
+    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"))
+    except json.JSONDecodeError as exc:
+        fail(f"{label} is malformed JSON: {exc.msg}")
+    if not isinstance(parsed, dict):
+        fail(f"{label} must be a JSON object")
+    return parsed
+
+
+def display_path(path: Path) -> str:
+    try:
+        rel = os.path.relpath(path, Path.cwd())
+    except ValueError:
+        rel = path.name
+    rel = rel.replace(os.sep, "/")
+    safe, _count = redact_string(rel)
+    return safe
+
+
+def store_paths(store_dir: str, receipt_id: str) -> tuple[Path, Path, Path]:
+    if not RECEIPT_ID_RE.fullmatch(receipt_id):
+        fail("receipt_id must be 16-64 lowercase hex chars")
+    root = normalize_allowed_first_absolute_symlink(Path(store_dir).expanduser())
+    return root, root / f"{receipt_id}.receipt.json", root / f"{receipt_id}.payload.json"
+
+
+def build_receipt_id(payload_without_id: dict[str, Any]) -> str:
+    basis = json_bytes(payload_without_id) + f"\n{time.time_ns()}:{os.getpid()}"
+    return hashlib.sha256(basis.encode("utf-8", errors="replace")).hexdigest()[:20]
+
+
+def build_payload(receipt_id: str, ranked: list[Candidate], query: str, redactions: int) -> dict[str, Any]:
+    return {
+        "tool": TOOL_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "receipt_id": receipt_id,
+        "created_at_unix": int(time.time()),
+        "query": query,
+        "candidate_count": len(ranked),
+        "redaction": {"redacted_values": redactions},
+        "tools": [
+            {
+                "name": cand.name,
+                "server": cand.server,
+                "description": cand.description,
+                "score": cand.score,
+                "rank": cand.rank,
+                "schema_bytes": byte_len_json(cand.schema),
+                "schema": cand.schema,
+            }
+            for cand in ranked
+        ],
+    }
+
+
+def compact_omitted(candidates: list[Candidate], limit: int) -> tuple[list[dict[str, Any]], int]:
+    items: list[dict[str, Any]] = []
+    for cand in candidates[:limit]:
+        items.append({
+            "name": cap_text(cand.name, MAX_LABEL_CHARS),
+            "server": cap_text(cand.server, MAX_LABEL_CHARS) if cand.server else None,
+            "reason": "below_top_k",
+            "score": cand.score,
+            "rank": cand.rank,
+        })
+    return items, max(0, len(candidates) - len(items))
+
+
+def retrieval_command(receipt_id: str, *, store_dir: str, tool_name: str | None = None) -> str:
+    parts = ["context-guard-tool-prune", "get", receipt_id]
+    if store_dir != DEFAULT_STORE_DIR:
+        parts.extend(["--store-dir", shlex.quote(store_dir)])
+    if tool_name is not None:
+        parts.extend(["--tool", shlex.quote(tool_name)])
+    parts.append("--json")
+    return " ".join(parts)
+
+
+def selected_tool_record(cand: Candidate, receipt_id: str, budget_left: int, *, store_dir: str) -> tuple[dict[str, Any], int]:
+    schema_size = byte_len_json(cand.schema)
+    record: dict[str, Any] = {
+        "name": cand.name,
+        "server": cand.server,
+        "score": cand.score,
+        "rank": cand.rank,
+        "description": cand.description,
+        "schema_bytes": schema_size,
+        "retrieval": retrieval_command(receipt_id, store_dir=store_dir, tool_name=cand.name),
+    }
+    if schema_size <= budget_left:
+        record["schema_included"] = True
+        record["schema"] = cand.schema
+        return record, schema_size
+    record["schema_included"] = False
+    record["schema_omitted_reason"] = "budget"
+    return record, 0
+
+
+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:
+        return candidate
+
+    result = json.loads(json_bytes(result))
+    omitted = result.get("omitted_tools")
+    while isinstance(omitted, list) and len(omitted) > 0:
+        keep = max(0, len(omitted) // 2)
+        result["omitted_tools"] = omitted[:keep]
+        result["omitted_tools_truncated"] = True
+        result["omitted_tools_summary"] = f"{result.get('omitted_count', 0)} tools omitted; list capped to fit --max-output-bytes"
+        candidate = json_bytes(result, indent=2) + "\n"
+        if byte_len_text(candidate) <= max_output_bytes:
+            return candidate
+        omitted = result.get("omitted_tools")
+
+    result["omitted_tools"] = []
+    result["omitted_tools_truncated"] = True
+    for item in result.get("selected_tools", []):
+        if isinstance(item, dict):
+            item.pop("description", None)
+    candidate = json_bytes(result, indent=2) + "\n"
+    if byte_len_text(candidate) <= max_output_bytes:
+        return candidate
+    fail(f"select report exceeds --max-output-bytes: {byte_len_text(candidate)} > {max_output_bytes}")
+
+
+def select_catalog(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")
+    top = bounded_int(args.top, default=DEFAULT_TOP, minimum=1, maximum=MAX_TOP, name="--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)
+    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(args.store_dir, 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=args.store_dir, 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}")
+
+    selected: list[dict[str, Any]] = []
+    selected_schema_bytes = 0
+    for cand in ranked[:top]:
+        record, used = selected_tool_record(cand, receipt_id, budget_bytes - selected_schema_bytes, store_dir=args.store_dir)
+        selected_schema_bytes += used
+        selected.append(record)
+    omitted_tools, omitted_truncated = compact_omitted(ranked[top:], MAX_OMITTED_TOOLS)
+    result = {
+        "tool": TOOL_NAME,
+        "schema_version": SCHEMA_VERSION,
+        "mode": "select",
+        "query": safe_query,
+        "top": top,
+        "budget_bytes": budget_bytes,
+        "selected_schema_bytes": selected_schema_bytes,
+        "candidate_count": len(ranked),
+        "selected_tools": selected,
+        "omitted_tools": omitted_tools,
+        "omitted_count": len(ranked[top:]),
+        "omitted_tools_truncated_count": omitted_truncated,
+        "receipt": {
+            **receipt,
+            "bytes": receipt_size,
+        },
+        "token_proxy": {"measurement": "estimated", "chars_per_token": TOKEN_PROXY_CHARS_PER_TOKEN},
+        "caveats": [
+            "Ranking is heuristic lexical overlap, not a correctness proof.",
+            "Token counts are estimated proxies; byte counts and schema budgets are observed UTF-8 bytes.",
+            "Use the receipt get command to retrieve full sanitized schemas before relying on omitted details.",
+        ],
+        "redaction": {"redacted_values": total_redactions},
+    }
+    rendered = shrink_result_for_output(result, 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 "")
+    if raw:
+        raw_path = Path(raw)
+        if raw_path.is_absolute():
+            fail("receipt payload_path must be relative")
+        if raw_path.name != expected_name:
+            fail("receipt payload_path does not match receipt_id")
+    return store_dir / expected_name
+
+
+def get_schema(args: argparse.Namespace) -> str:
+    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")
+    max_output_bytes = bounded_int(args.max_output_bytes, default=10_000_000, minimum=1, maximum=100_000_000, name="--max-output-bytes")
+    receipt_id = args.receipt_id
+    if not RECEIPT_ID_RE.fullmatch(receipt_id):
+        fail("receipt_id must be 16-64 lowercase hex chars")
+    store_dir, receipt_path, _payload = store_paths(args.store_dir, receipt_id)
+    reject_symlink_components(receipt_path)
+    receipt = read_private_json(receipt_path, max_bytes=max_receipt_bytes, label="receipt")
+    if receipt.get("receipt_id") != receipt_id:
+        fail("receipt id mismatch")
+    payload_path = payload_path_from_receipt(store_dir, receipt_id, receipt)
+    reject_symlink_components(payload_path)
+    expected_bytes = receipt.get("payload_bytes")
+    expected_sha = receipt.get("payload_sha256")
+    if not isinstance(expected_bytes, int) or expected_bytes < 0:
+        fail("receipt missing payload byte size")
+    if expected_bytes > max_payload_bytes:
+        fail(f"payload exceeds trusted size cap: {expected_bytes} > {max_payload_bytes}")
+    if not isinstance(expected_sha, str) or not re.fullmatch(r"[a-f0-9]{64}", expected_sha):
+        fail("receipt missing payload sha256")
+
+    payload_text, actual_size = read_private_text(payload_path, max_bytes=max_payload_bytes, label="payload")
+    if actual_size != expected_bytes:
+        fail(f"payload size mismatch: {actual_size} != {expected_bytes}")
+    actual_sha = sha256_text(payload_text.rstrip("\n"))
+    if actual_sha != expected_sha:
+        fail("payload sha256 mismatch")
+    try:
+        payload = json.loads(payload_text)
+    except json.JSONDecodeError as exc:
+        fail(f"payload is malformed JSON: {exc.msg}")
+    if not isinstance(payload, dict):
+        fail("payload must be a JSON object")
+    if payload.get("receipt_id") != receipt_id:
+        fail("payload receipt id mismatch")
+    tools = payload.get("tools")
+    if not isinstance(tools, list):
+        fail("payload tools missing")
+
+    if not args.tool:
+        result = {
+            "tool": TOOL_NAME,
+            "schema_version": SCHEMA_VERSION,
+            "mode": "get",
+            "receipt_id": receipt_id,
+            "tools": [item.get("name") for item in tools if isinstance(item, dict)],
+        }
+    else:
+        found = None
+        for item in tools:
+            if isinstance(item, dict) and item.get("name") == args.tool:
+                found = item
+                break
+        if found is None:
+            safe_tool, _tool_redactions = redact_string(args.tool)
+            fail(f"tool not found in receipt: {safe_tool}")
+        result = {
+            "tool": TOOL_NAME,
+            "schema_version": SCHEMA_VERSION,
+            "mode": "get",
+            "receipt_id": receipt_id,
+            "tool_name": args.tool,
+            "server": found.get("server"),
+            "schema": found.get("schema"),
+        }
+    sanitized_result, _redactions = sanitize_value(result)
+    if not isinstance(sanitized_result, dict):
+        fail("get result sanitation failed")
+    text = json_bytes(sanitized_result, indent=2) + "\n"
+    if byte_len_text(text) > max_output_bytes:
+        fail(f"get report exceeds --max-output-bytes: {byte_len_text(text)} > {max_output_bytes}")
+    return text
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Select bounded top-k tool/MCP schemas with local full-schema fallback receipts.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    select = sub.add_parser("select", help="rank a local catalog and emit a bounded selection report")
+    select.add_argument("--catalog", help="catalog JSON path; stdin is used when omitted")
+    select.add_argument("--query", default="", help="task query used for lexical ranking")
+    select.add_argument("--top", default=DEFAULT_TOP, help=f"number of tools to select (default: {DEFAULT_TOP})")
+    select.add_argument("--budget-bytes", default=DEFAULT_BUDGET_BYTES, help=f"inline selected schema byte budget (default: {DEFAULT_BUDGET_BYTES})")
+    select.add_argument("--max-catalog-bytes", default=DEFAULT_MAX_CATALOG_BYTES, help=f"maximum catalog JSON bytes (default: {DEFAULT_MAX_CATALOG_BYTES})")
+    select.add_argument("--max-output-bytes", default=DEFAULT_MAX_OUTPUT_BYTES, help=f"maximum rendered select JSON bytes (default: {DEFAULT_MAX_OUTPUT_BYTES})")
+    select.add_argument("--max-payload-bytes", default=DEFAULT_MAX_PAYLOAD_BYTES, help=f"maximum sanitized payload bytes (default: {DEFAULT_MAX_PAYLOAD_BYTES})")
+    select.add_argument("--max-receipt-bytes", default=DEFAULT_MAX_RECEIPT_BYTES, help=f"maximum compact receipt bytes (default: {DEFAULT_MAX_RECEIPT_BYTES})")
+    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)")
+
+    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")
+    get.add_argument("--store-dir", default=DEFAULT_STORE_DIR, help=f"receipt/payload directory (default: {DEFAULT_STORE_DIR})")
+    get.add_argument("--max-output-bytes", default=10_000_000, help="maximum rendered get JSON bytes")
+    get.add_argument("--max-payload-bytes", default=DEFAULT_MAX_PAYLOAD_BYTES, help=f"maximum trusted payload bytes (default: {DEFAULT_MAX_PAYLOAD_BYTES})")
+    get.add_argument("--max-receipt-bytes", default=DEFAULT_MAX_RECEIPT_BYTES, help=f"maximum trusted receipt bytes (default: {DEFAULT_MAX_RECEIPT_BYTES})")
+    get.add_argument("--json", action="store_true", help="emit JSON (default and only stable output contract)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "select":
+            sys.stdout.write(select_catalog(args))
+            return 0
+        if args.command == "get":
+            sys.stdout.write(get_schema(args))
+            return 0
+        parser.print_help(sys.stderr)
+        return 2
+    except ToolPruneError as exc:
+        print(f"{TOOL_NAME}: {exc}", file=sys.stderr)
+        return 1
+    except BrokenPipeError:
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())