@ictechgy/context-guard 0.4.1 → 0.4.4

package/context-guard-kit/context_compress.py

@@ -44,6 +44,55 @@ CODE_SIGNAL_RE = re.compile(
     r"(^\s*(def |class |function |func |import |from \S+ import |public |private |const |let |var |#include|package )"
     r"|[{};]\s*$|=>|::)"
 )
+CODE_FENCE_RE = re.compile(r"(?m)^\s*```")
+JSON_KEY_RE = re.compile(r'"(?:[^"\\]|\\.)*"\s*:')
+QUOTED_STRING_RE = re.compile(r"""(?x)
+    "(?:[^"\\]|\\.)*" |
+    '(?:[^'\\]|\\.)*'
+""")
+HASH_RE = re.compile(r"\b(?:[0-9a-fA-F]{32,}|sha256:[0-9a-fA-F]{32,})\b")
+PATH_RE = re.compile(
+    r"(?x)(?:"
+    r"(?<![\w.-])/(?:[A-Za-z0-9._@%+=:-]+/)*[A-Za-z0-9._@%+=:-]+"
+    r"|"
+    r"\b[A-Za-z]:\\(?:[^\\\s:\"'<>|]+\\)*[^\\\s:\"'<>|]+"
+    r"|"
+    r"\b[A-Za-z0-9._-]+\#path:[0-9a-f]{12}\b"
+    r")"
+)
+STACK_FRAME_RE = re.compile(
+    r"(?m)^\s*(?:File\s+\"[^\"]+\",\s+line\s+\d+,\s+in\s+\S+|at\s+\S+.*\([^)]*:\d+(?::\d+)?\))"
+)
+IDENTIFIER_RE = re.compile(r"\b[A-Za-z_][A-Za-z0-9_]*(?:[A-Z][A-Za-z0-9_]*)?\b")
+NUMERIC_CONSTANT_RE = re.compile(r"(?<![\w.])[-+]?(?:0x[0-9A-Fa-f]+|\d+(?:\.\d+)?)(?![\w.])")
+PROTECTED_ZONE_KEYS = (
+    "code_fence",
+    "diff",
+    "identifier",
+    "numeric_constant",
+    "hash",
+    "path",
+    "stack_frame",
+    "quoted_string",
+    "json_key",
+)
+PROTECTED_ALLOWED_TRANSFORMS = (
+    "exact_dedupe",
+    "structural_window",
+    "line_truncate",
+    "whitespace_normalize",
+    "json_compact",
+    "artifact_retrieval",
+)
+PROTECTED_DENIED_TRANSFORMS = (
+    "semantic_compress",
+    "paraphrase",
+    "identifier_rewrite",
+    "numeric_rewrite",
+    "hash_rewrite",
+    "path_rewrite",
+    "quoted_literal_rewrite",
+)
 
 
 def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
@@ -173,6 +222,85 @@ def classify_content(text: str) -> str:
     return "prose"
 
 
+def protected_zone_counts(text: str) -> dict[str, int]:
+    """Conservatively count semantic-sensitive zones without storing raw spans.
+
+    The counts intentionally over-approximate. They are policy signals for later
+    transform gates, not a parser. Metadata must never include the matched path,
+    identifier, hash, or string contents because receipts are safe to share.
+    """
+    lines = text.splitlines()
+    fence_markers = len(CODE_FENCE_RE.findall(text))
+    diff_lines = sum(
+        1
+        for line in lines
+        if DIFF_FILE_HEADER_RE.match(line)
+        or DIFF_HUNK_RE.match(line)
+        or (line[:1] in "+-" and not line.startswith(("+++", "---")))
+    )
+    counts = {
+        "code_fence": (fence_markers + 1) // 2,
+        "diff": diff_lines,
+        "identifier": len(IDENTIFIER_RE.findall(text)),
+        "numeric_constant": len(NUMERIC_CONSTANT_RE.findall(text)),
+        "hash": len(HASH_RE.findall(text)),
+        "path": len(PATH_RE.findall(text)),
+        "stack_frame": len(STACK_FRAME_RE.findall(text)),
+        "quoted_string": len(QUOTED_STRING_RE.findall(text)),
+        "json_key": len(JSON_KEY_RE.findall(text)),
+    }
+    return {key: counts[key] for key in PROTECTED_ZONE_KEYS if counts.get(key, 0) > 0}
+
+
+def build_protected_policy(
+    *,
+    text: str,
+    content_type: str,
+    strategy_detail: dict[str, object],
+    lossy: bool,
+) -> dict[str, object]:
+    """Build an opt-in transform policy for protected zones.
+
+    Protection governs transform eligibility and exact-retrieval expectations.
+    It does not claim the section should be provider-cache-stable; cache ordering
+    is handled by `context-guard-cost compile`.
+    """
+    zone_counts = protected_zone_counts(text)
+    detected = bool(zone_counts)
+    strategy = str(strategy_detail.get("strategy") or "unknown")
+    retrieval_required = bool(detected and lossy)
+    return {
+        "enabled": True,
+        "detected": detected,
+        "content_type": content_type,
+        "zone_counts": zone_counts,
+        "semantic_compress": False,
+        "allowed_transforms": list(PROTECTED_ALLOWED_TRANSFORMS),
+        "denied_transforms": list(PROTECTED_DENIED_TRANSFORMS),
+        "retrieval_required": retrieval_required,
+        "retrieval_scope": "sanitized_full_input" if retrieval_required else "compressed_output",
+        "raw_spans_stored": False,
+        "policy_note": "Protected zones permit structural transforms only; no semantic/paraphrase rewrites.",
+        "strategy": {
+            "name": strategy,
+            "structural_only": True,
+        },
+    }
+
+
+def build_transform_policy(protected_policy: dict[str, object]) -> dict[str, object]:
+    """Summarize transform eligibility without embedding raw protected content."""
+    return {
+        "mode": "protected" if protected_policy.get("detected") else "structural_default",
+        "semantic_transforms_allowed": False,
+        "semantic_compress": False,
+        "allowed": list(PROTECTED_ALLOWED_TRANSFORMS),
+        "denied": list(PROTECTED_DENIED_TRANSFORMS),
+        "exact_retrieval_required": bool(protected_policy.get("retrieval_required")),
+        "raw_spans_stored": False,
+    }
+
+
 def _looks_like_json(stripped: str) -> bool:
     if stripped[0] not in "{[":
         return False
@@ -353,6 +481,7 @@ def build_metadata(
     input_truncated: bool,
     input_bytes: int,
     max_bytes: int,
+    protected_policy_enabled: bool = False,
 ) -> dict[str, object]:
     """Assemble the compress receipt: observed byte/line counts plus an estimated token proxy.
 
@@ -370,7 +499,7 @@ def build_metadata(
         if lossy
         else "Data-preserving: compact form is semantically equivalent to the sanitized input."
     )
-    return {
+    metadata: dict[str, object] = {
         "tool": "context-guard-kit.context_compress",
         "metadata_version": 1,
         "content_type": content_type,
@@ -407,6 +536,21 @@ def build_metadata(
         },
         "retrieval_hint": retrieval_hint,
     }
+    if protected_policy_enabled:
+        protected_policy = build_protected_policy(
+            text=original_text,
+            content_type=content_type,
+            strategy_detail=strategy_detail,
+            lossy=lossy,
+        )
+        metadata["protected_zone_policy"] = protected_policy
+        metadata["transform_policy"] = build_transform_policy(protected_policy)
+        if protected_policy.get("retrieval_required"):
+            metadata["retrieval_hint"] = (
+                "Protected lossy structural transform: store the full sanitized text with "
+                "`context-guard-artifact store` and retrieve exact slices before relying on omitted content."
+            )
+    return metadata
 
 
 def compress_text(
@@ -417,6 +561,7 @@ def compress_text(
     input_truncated: bool,
     input_bytes: int,
     max_bytes: int,
+    protected_policy_enabled: bool = False,
 ) -> tuple[str, dict[str, object]]:
     """Sanitize first, then classify and compress, then build the receipt.
 
@@ -446,6 +591,7 @@ def compress_text(
         input_truncated=input_truncated,
         input_bytes=input_bytes,
         max_bytes=max_bytes,
+        protected_policy_enabled=protected_policy_enabled,
     )
     return compressed, metadata
 
@@ -489,6 +635,7 @@ def run_compress(args: argparse.Namespace) -> int:
         input_truncated=input_truncated,
         input_bytes=input_bytes,
         max_bytes=max_bytes,
+        protected_policy_enabled=bool(args.protected_policy),
     )
     if args.json:
         payload = {"metadata": metadata, "content": compressed}
@@ -513,6 +660,11 @@ def build_parser() -> argparse.ArgumentParser:
         help="force a content type instead of auto-detecting (json/diff/log/search/code/prose)",
     )
     parser.add_argument("--json", action="store_true", help="emit JSON with metadata and compressed content")
+    parser.add_argument(
+        "--protected-policy",
+        action="store_true",
+        help="add opt-in protected-zone transform policy metadata to --json/--metadata-only receipts; default content is unchanged",
+    )
     parser.add_argument(
         "--metadata-only",
         action="store_true",

package/context-guard-kit/context_filter.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""Validate and apply bounded declarative command-output filters.
+
+This helper is intentionally opt-in. User filter configs live outside package
+code and invalid/no-match/failure cases pass command output through rather than
+risk hiding evidence.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+import json
+from pathlib import Path
+import re
+import shlex
+import subprocess
+import sys
+from typing import Any, Iterable
+
+SCHEMA_VERSION = "contextguard.filter-dsl.v1"
+TOOL_NAME = "context-guard-filter"
+MAX_CONFIG_BYTES = 1_000_000
+MAX_FILTERS = 100
+MAX_REGEXES_PER_FILTER = 20
+MAX_REGEX_CHARS = 500
+MAX_ARG_PARTS = 64
+MAX_ARG_CHARS = 200
+DEFAULT_MAX_CAPTURE_BYTES = 5_000_000
+MAX_CAPTURE_BYTES_LIMIT = 50_000_000
+DEFAULT_MAX_LINE_CHARS = 100_000
+MAX_LINE_CHARS_LIMIT = 1_000_000
+MAX_EMIT_LINES = 5_000
+DEFAULT_TIMEOUT_SECONDS = 600
+MAX_TIMEOUT_SECONDS = 86_400
+TIMEOUT_EXIT_CODE = 124
+FILTER_KEYS = {"id", "match", "passthrough_on_exit", "include_regex", "exclude_regex", "head_lines", "tail_lines", "max_lines"}
+MATCH_KEYS = {"argv_prefix", "argv_regex"}
+PROTECTED_BASENAMES = {
+    "git",
+    "gh",
+    "pytest",
+    "ruff",
+    "mypy",
+    "eslint",
+    "vitest",
+    "jest",
+}
+PROTECTED_NPM_TASKS = {"test", "lint"}
+PROTECTED_PYTHON_MODULES = {"pytest", "ruff", "mypy"}
+PROTECTED_DIRECT_NAMES = {"pytest", "ruff", "mypy", "eslint", "vitest", "jest", "tox"}
+PROTECTED_INTENT_TOKENS = {"test", "tests", "lint", "clippy"}
+
+
+@dataclass(frozen=True)
+class CompiledFilter:
+    id: str
+    argv_prefix: tuple[str, ...] | None
+    argv_regex: re.Pattern[str] | None
+    passthrough_on_exit: bool
+    include_regex: tuple[re.Pattern[str], ...]
+    exclude_regex: tuple[re.Pattern[str], ...]
+    head_lines: int | None
+    tail_lines: int | None
+    max_lines: int | None
+
+
+def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
+    try:
+        number = int(value)
+    except (TypeError, ValueError, OverflowError):
+        return default
+    return min(max(number, minimum), maximum)
+
+
+def compact(text: str, limit: int = 160) -> str:
+    text = " ".join(str(text).split())
+    if len(text) <= limit:
+        return text
+    return text[: max(0, limit - 20)] + f"…[trimmed:{len(text)}]"
+
+
+def read_json_limited(path: Path) -> tuple[Any | None, list[str]]:
+    try:
+        size = path.stat().st_size
+        if size > MAX_CONFIG_BYTES:
+            return None, [f"config file too large: {size}>{MAX_CONFIG_BYTES} bytes"]
+        raw = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return None, [f"could not read config: {exc.strerror or exc.__class__.__name__}"]
+    try:
+        return json.loads(raw), []
+    except json.JSONDecodeError as exc:
+        return None, [f"invalid JSON at line {exc.lineno}: {exc.msg}"]
+
+
+def validate_str_list(value: Any, *, field: str, errors: list[str], max_items: int = MAX_REGEXES_PER_FILTER) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        errors.append(f"{field} must be a list")
+        return []
+    if len(value) > max_items:
+        errors.append(f"{field} has too many items: {len(value)}>{max_items}")
+    out: list[str] = []
+    for idx, item in enumerate(value[:max_items]):
+        if not isinstance(item, str) or not item.strip():
+            errors.append(f"{field}[{idx}] must be a non-empty string")
+            continue
+        if len(item) > MAX_REGEX_CHARS:
+            errors.append(f"{field}[{idx}] exceeds {MAX_REGEX_CHARS} chars")
+            continue
+        out.append(item)
+    return out
+
+
+def compile_regexes(patterns: Iterable[str], *, field: str, errors: list[str]) -> tuple[re.Pattern[str], ...]:
+    compiled: list[re.Pattern[str]] = []
+    for idx, pattern in enumerate(patterns):
+        try:
+            compiled.append(re.compile(pattern))
+        except re.error as exc:
+            errors.append(f"{field}[{idx}] invalid regex: {compact(str(exc), 120)}")
+    return tuple(compiled)
+
+
+def bounded_optional_int(raw: Any, *, field: str, errors: list[str], minimum: int = 0) -> int | None:
+    if raw is None:
+        return None
+    if not isinstance(raw, int) or isinstance(raw, bool):
+        errors.append(f"{field} must be an integer")
+        return None
+    if raw < minimum or raw > MAX_EMIT_LINES:
+        errors.append(f"{field} out of bounds: {minimum}..{MAX_EMIT_LINES}")
+        return None
+    return raw
+
+
+def validate_config(raw: Any) -> tuple[list[CompiledFilter], list[str]]:
+    errors: list[str] = []
+    if not isinstance(raw, dict):
+        return [], ["config root must be a JSON object"]
+    unknown_root = sorted(set(raw) - {"schema_version", "filters"})
+    if unknown_root:
+        errors.append(f"unknown root keys: {', '.join(unknown_root)}")
+    if raw.get("schema_version") != SCHEMA_VERSION:
+        errors.append(f"schema_version must be {SCHEMA_VERSION}")
+    filters_raw = raw.get("filters")
+    if not isinstance(filters_raw, list) or not filters_raw:
+        errors.append("filters must be a non-empty list")
+        return [], errors
+    if len(filters_raw) > MAX_FILTERS:
+        errors.append(f"filters has too many items: {len(filters_raw)}>{MAX_FILTERS}")
+    seen_ids: set[str] = set()
+    compiled: list[CompiledFilter] = []
+    for idx, item in enumerate(filters_raw[:MAX_FILTERS]):
+        prefix = f"filters[{idx}]"
+        if not isinstance(item, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        unknown = sorted(set(item) - FILTER_KEYS)
+        if unknown:
+            errors.append(f"{prefix} unknown keys: {', '.join(unknown)}")
+        fid = item.get("id")
+        if not isinstance(fid, str) or not re.fullmatch(r"[A-Za-z0-9._-]{1,80}", fid):
+            errors.append(f"{prefix}.id must match [A-Za-z0-9._-] and be <=80 chars")
+            fid = f"invalid-{idx}"
+        elif fid in seen_ids:
+            errors.append(f"{prefix}.id duplicates {fid}")
+        seen_ids.add(str(fid))
+        match = item.get("match")
+        argv_prefix: tuple[str, ...] | None = None
+        argv_regex: re.Pattern[str] | None = None
+        if not isinstance(match, dict):
+            errors.append(f"{prefix}.match must be an object")
+        else:
+            unknown_match = sorted(set(match) - MATCH_KEYS)
+            if unknown_match:
+                errors.append(f"{prefix}.match unknown keys: {', '.join(unknown_match)}")
+            if "argv_prefix" in match:
+                parts = validate_str_list(match.get("argv_prefix"), field=f"{prefix}.match.argv_prefix", errors=errors, max_items=MAX_ARG_PARTS)
+                for part_idx, part in enumerate(parts):
+                    if len(part) > MAX_ARG_CHARS:
+                        errors.append(f"{prefix}.match.argv_prefix[{part_idx}] exceeds {MAX_ARG_CHARS} chars")
+                if parts:
+                    argv_prefix = tuple(parts)
+            if "argv_regex" in match:
+                pattern = match.get("argv_regex")
+                if not isinstance(pattern, str) or not pattern.strip():
+                    errors.append(f"{prefix}.match.argv_regex must be a non-empty string")
+                elif len(pattern) > MAX_REGEX_CHARS:
+                    errors.append(f"{prefix}.match.argv_regex exceeds {MAX_REGEX_CHARS} chars")
+                else:
+                    compiled_argv_regex = compile_regexes([pattern], field=f"{prefix}.match.argv_regex", errors=errors)
+                    argv_regex = compiled_argv_regex[0] if compiled_argv_regex else None
+            if not argv_prefix and argv_regex is None:
+                errors.append(f"{prefix}.match requires argv_prefix or argv_regex")
+        passthrough = item.get("passthrough_on_exit", True)
+        if not isinstance(passthrough, bool):
+            errors.append(f"{prefix}.passthrough_on_exit must be boolean")
+            passthrough = True
+        include = validate_str_list(item.get("include_regex"), field=f"{prefix}.include_regex", errors=errors)
+        exclude = validate_str_list(item.get("exclude_regex"), field=f"{prefix}.exclude_regex", errors=errors)
+        if len(include) + len(exclude) > MAX_REGEXES_PER_FILTER:
+            errors.append(f"{prefix} has too many regexes: {len(include) + len(exclude)}>{MAX_REGEXES_PER_FILTER}")
+        head = bounded_optional_int(item.get("head_lines"), field=f"{prefix}.head_lines", errors=errors)
+        tail = bounded_optional_int(item.get("tail_lines"), field=f"{prefix}.tail_lines", errors=errors)
+        max_lines = bounded_optional_int(item.get("max_lines"), field=f"{prefix}.max_lines", errors=errors, minimum=1)
+        compiled.append(CompiledFilter(
+            id=str(fid),
+            argv_prefix=argv_prefix,
+            argv_regex=argv_regex,
+            passthrough_on_exit=passthrough,
+            include_regex=compile_regexes(include, field=f"{prefix}.include_regex", errors=errors),
+            exclude_regex=compile_regexes(exclude, field=f"{prefix}.exclude_regex", errors=errors),
+            head_lines=head,
+            tail_lines=tail,
+            max_lines=max_lines,
+        ))
+    return compiled, errors
+
+
+def load_filters(path: Path) -> tuple[list[CompiledFilter], list[str]]:
+    raw, read_errors = read_json_limited(path)
+    if read_errors:
+        return [], read_errors
+    return validate_config(raw)
+
+
+def command_text(argv: list[str]) -> str:
+    try:
+        return shlex.join(argv)
+    except Exception:
+        return " ".join(argv)
+
+
+def filter_matches(flt: CompiledFilter, argv: list[str]) -> bool:
+    if flt.argv_prefix is not None and tuple(argv[: len(flt.argv_prefix)]) == flt.argv_prefix:
+        return True
+    if flt.argv_regex is not None and flt.argv_regex.search(command_text(argv)):
+        return True
+    return False
+
+
+def basename(arg: str) -> str:
+    return Path(arg).name.lower()
+
+
+def argv_signal_tokens(argv: list[str]) -> set[str]:
+    tokens: set[str] = set()
+    for arg in argv:
+        lowered = basename(arg)
+        if lowered:
+            tokens.add(lowered)
+        tokens.update(part for part in re.split(r"[^a-z0-9]+", lowered) if part)
+    return tokens
+
+
+def has_test_lint_signal(argv: list[str]) -> bool:
+    tokens = argv_signal_tokens(argv)
+    return bool(tokens & PROTECTED_DIRECT_NAMES or tokens & PROTECTED_INTENT_TOKENS)
+
+
+def is_protected_command(argv: list[str]) -> bool:
+    if not argv:
+        return False
+    first = basename(argv[0])
+    if first in PROTECTED_BASENAMES:
+        return True
+    if first in {"python", "python3"} and len(argv) >= 3 and argv[1] == "-m" and basename(argv[2]) in PROTECTED_PYTHON_MODULES:
+        return True
+    if first in {"npm", "pnpm", "yarn"} and len(argv) >= 2:
+        if argv[1] in PROTECTED_NPM_TASKS:
+            return True
+        if len(argv) >= 3 and argv[1] == "run" and has_test_lint_signal(argv[2:]):
+            return True
+        if len(argv) >= 3 and argv[1] in {"exec", "x", "dlx"} and has_test_lint_signal(argv[2:]):
+            return True
+    if first in {"npx", "bun", "make", "gradle", "gradlew", "mvn", "poetry", "uv", "pipenv", "hatch", "tox"} and has_test_lint_signal(argv):
+        return True
+    if first == "go" and len(argv) >= 2 and argv[1] == "test":
+        return True
+    if first == "cargo" and len(argv) >= 2 and argv[1] in {"test", "clippy"}:
+        return True
+    return False
+
+
+def cap_line(line: str, max_chars: int) -> str:
+    if len(line) <= max_chars:
+        return line
+    suffix = "\n" if line.endswith("\n") else ""
+    marker = f"...[line capped:{len(line)} chars]"
+    return line[: max(0, max_chars - len(marker) - len(suffix))] + marker + suffix
+
+
+def select_lines(lines: list[str], flt: CompiledFilter, max_line_chars: int) -> list[str]:
+    selected = [cap_line(line, max_line_chars) for line in lines]
+    if flt.include_regex:
+        selected = [line for line in selected if any(pattern.search(line) for pattern in flt.include_regex)]
+    if flt.exclude_regex:
+        selected = [line for line in selected if not any(pattern.search(line) for pattern in flt.exclude_regex)]
+    if flt.head_lines is not None or flt.tail_lines is not None:
+        head_n = flt.head_lines if flt.head_lines is not None else 0
+        tail_n = flt.tail_lines if flt.tail_lines is not None else 0
+        head = selected[:head_n] if head_n else []
+        tail = selected[-tail_n:] if tail_n else []
+        if head and tail:
+            seen_head_count = len(head)
+            tail = tail[max(0, seen_head_count + len(tail) - len(selected)):]
+        selected = head + tail
+    if flt.max_lines is not None and len(selected) > flt.max_lines:
+        selected = selected[:flt.max_lines]
+    if len(selected) > MAX_EMIT_LINES:
+        selected = selected[:MAX_EMIT_LINES]
+    return selected
+
+
+def validation_payload(valid: bool, errors: list[str], count: int = 0) -> dict[str, Any]:
+    return {"tool": TOOL_NAME, "schema_version": SCHEMA_VERSION, "mode": "validate", "valid": valid, "filter_count": count, "errors": errors}
+
+
+def print_validation(valid: bool, errors: list[str], count: int, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(validation_payload(valid, errors, count), ensure_ascii=False, sort_keys=True))
+    elif valid:
+        print(f"{TOOL_NAME}: valid filter config ({count} filter(s))")
+    else:
+        print(f"{TOOL_NAME}: invalid filter config", file=sys.stderr)
+        for error in errors:
+            print(f"- {error}", file=sys.stderr)
+
+
+def timeout_text(value: str | bytes | None) -> str:
+    if isinstance(value, str):
+        return value
+    return (value or b"").decode("utf-8", "replace")
+
+
+def run_command(argv: list[str], timeout_seconds: int) -> tuple[int, str, str, bool]:
+    try:
+        proc = subprocess.run(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, errors="replace", timeout=timeout_seconds)
+        return proc.returncode, proc.stdout or "", proc.stderr or "", False
+    except subprocess.TimeoutExpired as exc:
+        stdout = timeout_text(exc.stdout)
+        stderr = timeout_text(exc.stderr) + f"\n[{TOOL_NAME}] command timed out after {timeout_seconds}s\n"
+        return TIMEOUT_EXIT_CODE, stdout, stderr, True
+    except OSError as exc:
+        return 127, "", f"{TOOL_NAME}: command failed to start: {exc.strerror or exc.__class__.__name__}\n", False
+
+
+def emit_run_report(args: argparse.Namespace, payload: dict[str, Any]) -> None:
+    if payload.get("protected_nonzero"):
+        return
+    if args.json_report:
+        print(json.dumps(payload, ensure_ascii=False, sort_keys=True), file=sys.stderr)
+    elif payload.get("decision") == "passthrough" and payload.get("reason") not in {"no-match", "nonzero-passthrough"}:
+        print(f"{TOOL_NAME}: passthrough: {payload.get('reason')}", file=sys.stderr)
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    filters, errors = load_filters(Path(args.config).expanduser())
+    print_validation(not errors, errors, len(filters), args.json)
+    return 0 if not errors else 2
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    command = list(args.command)
+    if command and command[0] == "--":
+        command = command[1:]
+    if not command:
+        print(f"{TOOL_NAME}: missing command", file=sys.stderr)
+        return 2
+    max_capture = bounded_int(args.max_capture_bytes, DEFAULT_MAX_CAPTURE_BYTES, 1, MAX_CAPTURE_BYTES_LIMIT)
+    max_line_chars = bounded_int(args.max_line_chars, DEFAULT_MAX_LINE_CHARS, 1, MAX_LINE_CHARS_LIMIT)
+    timeout_seconds = bounded_int(args.timeout_seconds, DEFAULT_TIMEOUT_SECONDS, 1, MAX_TIMEOUT_SECONDS)
+    filters, errors = load_filters(Path(args.config).expanduser())
+    rc, stdout_text, stderr_text, timed_out = run_command(command, timeout_seconds)
+    output = stdout_text + stderr_text
+    output_bytes = len(output.encode("utf-8", "replace"))
+    protected_nonzero = rc != 0 and is_protected_command(command)
+    report: dict[str, Any] = {"tool": TOOL_NAME, "schema_version": SCHEMA_VERSION, "mode": "run", "command_exit_code": rc, "decision": "passthrough", "reason": "unclassified", "protected_nonzero": protected_nonzero}
+    if timed_out:
+        report["reason"] = "timeout"
+    elif errors:
+        report["reason"] = "invalid-config"
+        report["errors"] = errors[:10]
+    elif output_bytes > max_capture:
+        report["reason"] = "capture-limit"
+        report["output_bytes"] = output_bytes
+        report["max_capture_bytes"] = max_capture
+    else:
+        matched = next((flt for flt in filters if filter_matches(flt, command)), None)
+        if matched is None:
+            report["reason"] = "no-match"
+        elif protected_nonzero:
+            report["reason"] = "protected-nonzero"
+            report["filter_id"] = matched.id
+        elif rc != 0 and matched.passthrough_on_exit:
+            report["reason"] = "nonzero-passthrough"
+            report["filter_id"] = matched.id
+        else:
+            try:
+                lines = output.splitlines(keepends=True)
+                filtered = select_lines(lines, matched, max_line_chars)
+            except re.error as exc:
+                report["reason"] = f"filter-error:{compact(str(exc), 80)}"
+                report["filter_id"] = matched.id
+            else:
+                if output and not filtered:
+                    report["reason"] = "empty-output-fallback"
+                    report["filter_id"] = matched.id
+                else:
+                    sys.stdout.write("".join(filtered))
+                    report.update({"decision": "filtered", "reason": "matched", "filter_id": matched.id, "input_lines": len(lines), "output_lines": len(filtered)})
+                    emit_run_report(args, report)
+                    return rc
+    sys.stdout.write(stdout_text)
+    sys.stderr.write(stderr_text)
+    emit_run_report(args, report)
+    return rc
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=TOOL_NAME, description="Validate and apply bounded declarative command-output filters. Filtered mode applies line rules to combined stdout+stderr and writes the filtered result to stdout; passthrough mode preserves stdout/stderr streams.")
+    sub = parser.add_subparsers(dest="command_name", required=True)
+    validate = sub.add_parser("validate", help="validate a filter DSL JSON file")
+    validate.add_argument("--config", required=True, help="path to user-owned filter JSON")
+    validate.add_argument("--json", action="store_true", help="emit validation result as JSON")
+    validate.set_defaults(func=cmd_validate)
+    run = sub.add_parser("run", help="run a command and apply the first matching safe filter")
+    run.add_argument("--config", required=True, help="path to user-owned filter JSON")
+    run.add_argument("--json-report", action="store_true", help="emit filter decision JSON to stderr; protected nonzero passthrough suppresses reports to preserve raw stderr")
+    run.add_argument("--max-capture-bytes", type=int, default=DEFAULT_MAX_CAPTURE_BYTES)
+    run.add_argument("--max-line-chars", type=int, default=DEFAULT_MAX_LINE_CHARS)
+    run.add_argument("--timeout-seconds", type=int, default=DEFAULT_TIMEOUT_SECONDS)
+    run.add_argument("command", nargs=argparse.REMAINDER)
+    run.set_defaults(func=cmd_run)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/context-guard-kit/context_guard_cli.py

@@ -19,6 +19,7 @@ PACKAGE_NAME = "@ictechgy/context-guard"
 
 HELPER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
     "setup": ("context-guard-setup",),
+    "doctor": ("context-guard-setup", "--verify"),
     "audit": ("context-guard-audit",),
     "diet": ("context-guard-diet",),
     "scan": ("context-guard-diet", "scan"),
@@ -26,10 +27,12 @@ HELPER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
     "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",),
     "bench": ("context-guard-bench",),
     "read-symbol": ("context-guard-read-symbol",),
     "rewrite-bash": ("context-guard-rewrite-bash",),