@ictechgy/context-guard 0.4.10 → 0.4.12

package/plugins/context-guard/bin/context-guard-filter

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import argparse
 import codecs
+import collections
+import itertools
 from dataclasses import dataclass
 import json
 import os
@@ -455,26 +457,94 @@ def cap_line(line: str, max_chars: int) -> str:
     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)]
+LINE_BOUNDARY_CHARS = {"\n", "\r", "\v", "\f", "\x1c", "\x1d", "\x1e", "\x85", "\u2028", "\u2029"}
+
+
+@dataclass
+class LineSelection:
+    lines: list[str]
+    input_lines: int
+    input_complete: bool
+
+
+def iter_text_lines_keepends(text: str) -> Iterable[str]:
+    """Yield lines with Python splitlines(keepends=True) boundaries without a list."""
+    start = 0
+    index = 0
+    length = len(text)
+    while index < length:
+        char = text[index]
+        if char == "\r" and index + 1 < length and text[index + 1] == "\n":
+            yield text[start : index + 2]
+            index += 2
+            start = index
+            continue
+        if char in LINE_BOUNDARY_CHARS:
+            yield text[start : index + 1]
+            index += 1
+            start = index
+            continue
+        index += 1
+    if start < length:
+        yield text[start:]
+
+
+def line_matches_filter(line: str, flt: CompiledFilter) -> bool:
+    if flt.include_regex and not any(pattern.search(line) for pattern in flt.include_regex):
+        return False
+    if flt.exclude_regex and any(pattern.search(line) for pattern in flt.exclude_regex):
+        return False
+    return True
+
+
+def select_lines_with_stats(lines: Iterable[str], flt: CompiledFilter, max_line_chars: int) -> LineSelection:
+    source_count = 0
+    matched_count = 0
+    input_complete = True
     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
+        head: list[str] = []
+        tail: collections.deque[str] = collections.deque(maxlen=tail_n)
+        for source_line in lines:
+            source_count += 1
+            line = cap_line(source_line, max_line_chars)
+            if not line_matches_filter(line, flt):
+                continue
+            matched_count += 1
+            if head_n and len(head) < head_n:
+                head.append(line)
+            if tail_n:
+                tail.append(line)
+            elif head_n and len(head) >= head_n:
+                input_complete = False
+                break
+        tail_list = list(tail)
+        if head and tail_list:
+            tail_list = tail_list[max(0, len(head) + len(tail_list) - matched_count):]
+        selected = head + tail_list
+    else:
+        limit = min(flt.max_lines if flt.max_lines is not None else MAX_EMIT_LINES, MAX_EMIT_LINES)
+        selected = []
+        for source_line in lines:
+            source_count += 1
+            line = cap_line(source_line, max_line_chars)
+            if not line_matches_filter(line, flt):
+                continue
+            matched_count += 1
+            selected.append(line)
+            if len(selected) >= limit:
+                input_complete = False
+                break
     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
+    return LineSelection(selected, source_count, input_complete)
+
+
+def select_lines(lines: Iterable[str], flt: CompiledFilter, max_line_chars: int) -> list[str]:
+    return select_lines_with_stats(lines, flt, max_line_chars).lines
 
 
 def validation_payload(valid: bool, errors: list[str], count: int = 0) -> dict[str, Any]:
@@ -720,7 +790,6 @@ def cmd_run(args: argparse.Namespace) -> int:
     filters, errors = load_filters(Path(args.config).expanduser())
     result = run_command(command, timeout_seconds, max_capture)
     rc = result.returncode
-    output = result.stdout_text + result.stderr_text
     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 result.timed_out:
@@ -746,18 +815,19 @@ def cmd_run(args: argparse.Namespace) -> int:
             report["filter_id"] = matched.id
         else:
             try:
-                lines = output.splitlines(keepends=True)
-                filtered = select_lines(lines, matched, max_line_chars)
+                source_lines = itertools.chain(iter_text_lines_keepends(result.stdout_text), iter_text_lines_keepends(result.stderr_text))
+                selection = select_lines_with_stats(source_lines, matched, max_line_chars)
+                filtered = selection.lines
             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:
+                if (result.stdout_text or result.stderr_text) 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)})
+                    report.update({"decision": "filtered", "reason": "matched", "filter_id": matched.id, "input_lines": selection.input_lines, "input_lines_complete": selection.input_complete, "output_lines": len(filtered)})
                     emit_run_report(args, report)
                     return rc
     if not result.passthrough_emitted:

package/plugins/context-guard/bin/context-guard-pack

@@ -53,6 +53,8 @@ SUGGEST_WHOLE_FILE_MAX_LINES = 120
 MAX_SUGGEST_INPUT_BYTES = 256_000
 MAX_QUERY_SCAN_FILES = 2_000
 MAX_QUERY_SCAN_BYTES_PER_FILE = 200_000
+MAX_GIT_LS_FILES_OUTPUT_BYTES = MAX_QUERY_SCAN_FILES * 512
+GIT_LS_FILES_READ_CHUNK_BYTES = 64 * 1024
 MAX_REPO_MAP_FILES = 1_000
 MAX_REPO_MAP_SCAN_FILES = 160
 MAX_REPO_MAP_BYTES_PER_FILE = 120_000
@@ -62,6 +64,11 @@ MAX_REPO_MAP_GRAPH_RANK_ENTRIES = 30
 MAX_REPO_MAP_RETRIEVAL_HINTS = 30
 MAX_REPO_MAP_SECRET_RISK_FILES = 20
 MAX_ADAPTIVE_K_SCORE_SAMPLES = 200
+MAX_ADAPTIVE_K_SELECTED_EVIDENCE = 12
+MAX_ADAPTIVE_K_OMITTED_EVIDENCE = 12
+MAX_ADAPTIVE_K_REASON_COUNTS = 12
+MAX_ADAPTIVE_K_VERIFICATION_HINTS = 12
+ADAPTIVE_K_POLICIES = ("balanced", "recall", "precision")
 MAX_SYMBOL_MEMORY_ITEMS = 12
 MAX_SYMBOL_MEMORY_GRAPH_ITEMS = 12
 PACK_DIR = ".context-guard/packs"
@@ -364,6 +371,16 @@ def bounded_int(value: object, default: int, minimum: int, maximum: int) -> int:
     return min(max(number, minimum), maximum)
 
 
+def adaptive_k_threshold(value: object) -> float:
+    try:
+        number = float(value)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise argparse.ArgumentTypeError("adaptive-k threshold must be a number between 0.0 and 1.0") from exc
+    if not 0.0 <= number <= 1.0:
+        raise argparse.ArgumentTypeError("adaptive-k threshold must be between 0.0 and 1.0")
+    return number
+
+
 def cap_label(value: object, default: str | None = None, limit: int = MAX_LABEL_CHARS) -> str | None:
     if value is None:
         return default
@@ -940,6 +957,29 @@ def metadata_size(data: dict[str, Any]) -> int:
     return len(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True).encode("utf-8", errors="replace")) + 1
 
 
+def receipt_working_copy(data: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+    """Copy receipt metadata without deep-copying or serializing an oversized pack body.
+
+    The pack body is already an immutable string in normal builds and stdout remains
+    authoritative for it.  When it cannot possibly fit under the receipt cap by
+    itself, omit it before the first receipt-size probe so capping work only touches
+    metadata previews.
+    """
+    receipt: dict[str, Any] = {}
+    pack_omitted = False
+    for key, value in data.items():
+        if key == "pack" and isinstance(value, str):
+            if len(value.encode("utf-8", errors="replace")) > MAX_RECEIPT_BYTES:
+                pack_omitted = True
+                continue
+            receipt[key] = value
+            continue
+        receipt[key] = copy.deepcopy(value)
+    if pack_omitted:
+        receipt["pack_omitted_from_receipt"] = True
+    return receipt, pack_omitted
+
+
 def artifact_failure(error: str, *, bytes_count: int = 0, capped: bool = False) -> dict[str, Any]:
     return {
         "stored": False,
@@ -1096,8 +1136,11 @@ def finalize_receipt_size(receipt: dict[str, Any]) -> int:
 
 
 def shrink_receipt_for_write(data: dict[str, Any]) -> tuple[dict[str, Any], bool]:
-    receipt = copy.deepcopy(data)
-    capped = False
+    receipt, pack_omitted = receipt_working_copy(data)
+    capped = pack_omitted
+    if pack_omitted:
+        receipt.setdefault("artifact", {})["capped"] = True
+        receipt.setdefault("artifact", {})["cap_bytes"] = MAX_RECEIPT_BYTES
     if metadata_size(receipt) <= MAX_RECEIPT_BYTES:
         return receipt, capped
     capped = True
@@ -1488,19 +1531,81 @@ def collect_output_candidates(
 
 
 def git_ls_files(root: Path) -> list[str]:
+    def read_stdout_capped(proc: subprocess.Popen[bytes], limit: int, timeout_seconds: float) -> tuple[bytes, bool]:
+        if proc.stdout is None:
+            return b"", False
+        chunks: list[bytes] = []
+        total = 0
+        capped = False
+        timed_out = False
+
+        def reader() -> None:
+            nonlocal total, capped
+            try:
+                while total <= limit:
+                    chunk = proc.stdout.read(min(GIT_LS_FILES_READ_CHUNK_BYTES, limit + 1 - total))
+                    if not chunk:
+                        break
+                    chunks.append(chunk)
+                    total += len(chunk)
+                    if total > limit:
+                        capped = True
+                        break
+            finally:
+                if capped and proc.poll() is None:
+                    try:
+                        proc.terminate()
+                    except OSError:
+                        pass
+                try:
+                    proc.stdout.close()
+                except OSError:
+                    pass
+
+        thread = threading.Thread(target=reader, daemon=True)
+        thread.start()
+        thread.join(timeout_seconds)
+        if thread.is_alive() and proc.poll() is None:
+            timed_out = True
+            try:
+                proc.kill()
+            except OSError:
+                pass
+        try:
+            proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            try:
+                proc.kill()
+            except OSError:
+                pass
+            try:
+                proc.wait(timeout=2)
+            except subprocess.TimeoutExpired:
+                pass
+        thread.join(0.2)
+        raw_output = b"".join(chunks)[:limit]
+        complete = proc.returncode == 0 and not capped and not timed_out and raw_output.endswith(b"\0")
+        return raw_output, complete
+
+    raw = b""
+    git_returncode: int | None = None
     try:
-        proc = subprocess.run(
+        proc = subprocess.Popen(
             ["git", "-C", str(root), "ls-files", "-z"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.DEVNULL,
             text=False,
-            capture_output=True,
-            timeout=10,
-            check=False,
         )
+        raw, _git_complete = read_stdout_capped(proc, MAX_GIT_LS_FILES_OUTPUT_BYTES, 10)
+        git_returncode = proc.returncode
     except (OSError, subprocess.TimeoutExpired):
         proc = None
-    if proc is not None and proc.returncode == 0:
-        raw = proc.stdout[: MAX_QUERY_SCAN_FILES * 512]
+    if raw:
+        if not raw.endswith(b"\0"):
+            raw = raw.rsplit(b"\0", 1)[0] if b"\0" in raw else b""
         return [part.decode("utf-8", "replace") for part in raw.split(b"\0") if part][:MAX_QUERY_SCAN_FILES]
+    if git_returncode == 0 or (git_returncode is not None and git_returncode < 0):
+        return []
     out: list[str] = []
     skip_dirs = {".git", ".omx", ".context-guard", "node_modules", "dist", "build", "__pycache__"}
     for current, dirs, files in os.walk(root):
@@ -1884,6 +1989,155 @@ def score_gap_advice(scores: list[int], requested_top: int) -> tuple[int, dict[s
     return max(1, elbow_k), {"after_rank": gap_index + 1, "delta": max_gap, "ratio": ratio}, reasons
 
 
+def clamp_proxy(value: float) -> float:
+    return min(1.0, max(0.0, round(value, 4)))
+
+
+def adaptive_policy_recommended_k(
+    *,
+    policy: str,
+    requested_top: int,
+    score_elbow_k: int,
+    budget_fit_k: int,
+    candidate_count: int,
+) -> int:
+    candidate_limit = min(max(0, candidate_count), MAX_SUGGEST_TOP)
+    if candidate_limit == 0 or budget_fit_k <= 0:
+        return 0
+    if policy == "recall":
+        policy_k = max(requested_top, score_elbow_k)
+    elif policy == "precision":
+        policy_k = min(score_elbow_k, requested_top)
+    else:
+        policy_k = score_elbow_k
+    return min(max(0, policy_k), max(0, budget_fit_k), candidate_limit)
+
+
+def adaptive_path_label(value: object) -> str:
+    raw = "" if value is None else str(value)
+    if CONTROL_CHAR_RE.search(raw) or SECRET_CONTENT_RE.search(raw) or SECRET_PATH_COMPONENT_RE.search(raw):
+        return f"redacted-path#path:{sha256_text(raw)[:12]}"
+    rel, _reason = lexical_rel(raw)
+    if rel is None:
+        return safe_raw_path_label(raw)
+    display, _redacted = display_rel_path(rel.as_posix())
+    return display
+
+
+def actionable_adaptive_path(value: object) -> tuple[str | None, str | None]:
+    raw = "" if value is None else str(value)
+    if not raw:
+        return None, "missing_path"
+    if REDACTED_PATH_COMPONENT in raw or "[REDACTED" in raw:
+        return None, "redacted_path"
+    if CONTROL_CHAR_RE.search(raw) or SECRET_CONTENT_RE.search(raw) or SECRET_PATH_COMPONENT_RE.search(raw):
+        return None, "unsafe_path"
+    rel, reason = lexical_rel(raw)
+    if rel is None:
+        return None, reason or "unsafe_path"
+    return rel.as_posix(), None
+
+
+def adaptive_lines(value: object) -> dict[str, int] | None:
+    if not isinstance(value, dict):
+        return None
+    try:
+        start = int(value.get("start"))
+        end = int(value.get("end"))
+    except (TypeError, ValueError, OverflowError):
+        return None
+    if start < 1 or end < start:
+        return None
+    return {"start": start, "end": end}
+
+
+def adaptive_retrieval_hint(item: dict[str, Any]) -> dict[str, Any]:
+    path, path_reason = actionable_adaptive_path(item.get("path"))
+    lines = adaptive_lines(item.get("lines") or item.get("included_lines") or item.get("requested_lines"))
+    omitted_reason = item.get("retrieval_omitted_reason")
+    if path_reason:
+        return {"type": "slice", "available": False, "reason": str(omitted_reason or path_reason)}
+    if lines is None:
+        return {"type": "slice", "available": False, "reason": "missing_lines"}
+    if not item.get("retrieval_cli"):
+        return {"type": "slice", "available": False, "reason": str(omitted_reason or "missing_retrieval_hint")}
+    return {"type": "slice", "available": True, "path": path, "lines": lines}
+
+
+def adaptive_selected_evidence(selected: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    evidence: list[dict[str, Any]] = []
+    for rank, item in enumerate(selected[:MAX_ADAPTIVE_K_SELECTED_EVIDENCE], start=1):
+        entry: dict[str, Any] = {
+            "rank": rank,
+            "path": adaptive_path_label(item.get("path")),
+            "score": max(0, int(item.get("score", item.get("priority", 0)) or 0)),
+            "reason": cap_label(item.get("reason"), default="local heuristic", limit=MAX_REASON_CHARS),
+            "retrieval_hint": adaptive_retrieval_hint(item),
+        }
+        lines = adaptive_lines(item.get("lines"))
+        if lines is not None:
+            entry["lines"] = lines
+        evidence.append(entry)
+    return evidence
+
+
+def adaptive_omitted_evidence(omitted: list[dict[str, Any]]) -> dict[str, Any]:
+    reason_counts: dict[str, int] = {}
+    sources: list[dict[str, Any]] = []
+    for item in omitted:
+        reason = cap_label(item.get("reason"), default="unknown", limit=MAX_REASON_CHARS) or "unknown"
+        reason_counts[reason] = reason_counts.get(reason, 0) + 1
+        if len(sources) >= MAX_ADAPTIVE_K_OMITTED_EVIDENCE:
+            continue
+        source: dict[str, Any] = {
+            "path": adaptive_path_label(item.get("path")),
+            "reason": reason,
+            "priority": max(0, int(item.get("priority", 0) or 0)),
+        }
+        lines = adaptive_lines(item.get("requested_lines") or item.get("lines"))
+        if lines is not None:
+            source["lines"] = lines
+        hint = adaptive_retrieval_hint(item)
+        if hint.get("available") or hint.get("reason") in {"redacted_path", "unsafe_root_path", "unsafe_path"}:
+            source["retrieval_hint"] = hint
+        sources.append(source)
+    counts = [
+        {"reason": reason, "count": count}
+        for reason, count in sorted(reason_counts.items(), key=lambda pair: (-pair[1], pair[0]))[:MAX_ADAPTIVE_K_REASON_COUNTS]
+    ]
+    return {
+        "omitted_count": len(omitted),
+        "sources_capped": len(omitted) > len(sources),
+        "sources": sources,
+        "reason_counts": counts,
+    }
+
+
+def adaptive_source_verification(selected: list[dict[str, Any]]) -> dict[str, Any]:
+    hints: list[dict[str, Any]] = []
+    available = 0
+    for rank, item in enumerate(selected[:MAX_ADAPTIVE_K_VERIFICATION_HINTS], start=1):
+        hint = adaptive_retrieval_hint(item)
+        if hint.get("available"):
+            available += 1
+        record: dict[str, Any] = {
+            "rank": rank,
+            "path": adaptive_path_label(item.get("path")),
+            "retrieval_hint": hint,
+        }
+        hints.append(record)
+    return {
+        "requires_exact_source_before_edits": True,
+        "format": "structured_relative_slice_hints",
+        "selected_count": len(selected),
+        "hint_count": len(hints),
+        "hints_capped": len(selected) > len(hints),
+        "available_hint_count": available,
+        "omitted_hint_count": len(hints) - available,
+        "hints": hints,
+    }
+
+
 def build_adaptive_k_advisory(
     *,
     candidates: list[SuggestCandidate],
@@ -1892,7 +2146,12 @@ def build_adaptive_k_advisory(
     requested_top: int,
     budget_bytes: int,
     estimated_pack_bytes: int,
+    policy: str = "balanced",
+    min_recall_proxy: float = 0.0,
+    min_precision_proxy: float = 0.0,
 ) -> dict[str, Any]:
+    if policy not in ADAPTIVE_K_POLICIES:
+        policy = "balanced"
     sampled_candidates = candidates[:MAX_ADAPTIVE_K_SCORE_SAMPLES]
     scores = [max(0, int(candidate.score)) for candidate in sampled_candidates]
     score_elbow_k, max_gap_details, reason_codes = score_gap_advice(scores, requested_top)
@@ -1924,19 +2183,36 @@ def build_adaptive_k_advisory(
     if not candidates:
         recommended_k = 0
     else:
-        recommended_k = min(
-            max(0, score_elbow_k),
-            max(0, budget_fit_k),
-            len(candidates),
-            MAX_SUGGEST_TOP,
+        recommended_k = adaptive_policy_recommended_k(
+            policy=policy,
+            requested_top=requested_top,
+            score_elbow_k=score_elbow_k,
+            budget_fit_k=budget_fit_k,
+            candidate_count=len(candidates),
         )
     score_values_asc = sorted(scores)
     top_score = score_values_asc[-1] if score_values_asc else 0
+    recall_proxy = clamp_proxy(selected_score_mass / analyzed_score_mass) if analyzed_score_mass else 0.0
+    precision_proxy = (
+        clamp_proxy((selected_score_mass / max(1, selected_count)) / max(1, top_score))
+        if selected_count
+        else 0.0
+    )
+    recall_gate_passed = recall_proxy >= min_recall_proxy
+    precision_gate_passed = precision_proxy >= min_precision_proxy
+    gate_status = "pass" if recall_gate_passed and precision_gate_passed else "failed"
     return {
         "schema_version": ADAPTIVE_K_SCHEMA_VERSION,
         "mode": "advisory",
         "requested_top": requested_top,
         "recommended_k": recommended_k,
+        "policy": {
+            "name": policy,
+            "available_policies": list(ADAPTIVE_K_POLICIES),
+            "changes_manifest_or_pack": False,
+            "measurement_basis": "current_selected_sources_not_policy_applied_rebuild",
+            "status": "evaluated",
+        },
         "recommendation": {
             "apply": False,
             "reason_codes": sorted(set(reason_codes)),
@@ -1963,25 +2239,46 @@ def build_adaptive_k_advisory(
             "average_selected_bytes": average_selected_bytes,
             "budget_fit_k": budget_fit_k,
         },
+        "regression_gates": {
+            "status": gate_status,
+            "measurement_basis": "current_selected_sources_not_policy_applied_rebuild",
+            "comparison": "observed_greater_than_or_equal_threshold",
+            "recall_proxy": {
+                "observed": recall_proxy,
+                "minimum": min_recall_proxy,
+                "passed": recall_gate_passed,
+            },
+            "precision_proxy": {
+                "observed": precision_proxy,
+                "minimum": min_precision_proxy,
+                "passed": precision_gate_passed,
+            },
+        },
         "recall_precision_proxy": {
             "measurement": "local_score_mass_proxy",
+            "range": "clamped_0_1",
+            "measurement_basis": "current_selected_sources_not_policy_applied_rebuild",
             "selected_score_mass": selected_score_mass,
             "analyzed_score_mass": analyzed_score_mass,
-            "recall_proxy": round(selected_score_mass / analyzed_score_mass, 4) if analyzed_score_mass else 0.0,
-            "precision_proxy": (
-                round((selected_score_mass / max(1, selected_count)) / max(1, top_score), 4)
-                if selected_count
-                else 0.0
-            ),
+            "recall_proxy": recall_proxy,
+            "precision_proxy": precision_proxy,
             "selected_count": selected_count,
             "candidate_count": len(candidates),
         },
+        "selected_evidence": {
+            "selected_count": selected_count,
+            "items_capped": selected_count > MAX_ADAPTIVE_K_SELECTED_EVIDENCE,
+            "items": adaptive_selected_evidence(selected),
+        },
+        "omitted_evidence": adaptive_omitted_evidence(omitted),
+        "source_verification": adaptive_source_verification(selected),
         "claim_boundary": {
             "deterministic_local_only": True,
             "no_model_network_or_embedding": True,
             "token_counts_are_estimated_proxies": True,
             "provider_token_or_cost_savings_claim_allowed": False,
             "advisory_does_not_change_manifest_or_pack": True,
+            "selectable_policy_changes_manifest_or_pack": False,
         },
     }
 
@@ -2152,6 +2449,9 @@ def suggest_pack(root: Path, args: argparse.Namespace, *, root_arg: str) -> tupl
             requested_top=top,
             budget_bytes=budget,
             estimated_pack_bytes=estimated_pack_bytes,
+            policy=getattr(args, "adaptive_k_policy", "balanced"),
+            min_recall_proxy=float(getattr(args, "adaptive_k_min_recall_proxy", 0.0) or 0.0),
+            min_precision_proxy=float(getattr(args, "adaptive_k_min_precision_proxy", 0.0) or 0.0),
         )
     return payload, 0
 
@@ -3063,6 +3363,8 @@ def print_adaptive_k_text(payload: dict[str, Any]) -> None:
         else {}
     )
     budget_fit = adaptive.get("budget_fit", {}) if isinstance(adaptive.get("budget_fit"), dict) else {}
+    policy = adaptive.get("policy", {}) if isinstance(adaptive.get("policy"), dict) else {}
+    regression_gates = adaptive.get("regression_gates", {}) if isinstance(adaptive.get("regression_gates"), dict) else {}
     reason_codes = recommendation.get("reason_codes", [])
     if isinstance(reason_codes, list):
         reason_text = ",".join(str(item) for item in reason_codes[:5])
@@ -3071,6 +3373,8 @@ def print_adaptive_k_text(payload: dict[str, Any]) -> None:
     print(
         "adaptive-k: "
         f"recommended={adaptive.get('recommended_k', 0)}/{adaptive.get('requested_top', 0)} "
+        f"policy={policy.get('name', 'balanced')} "
+        f"gates={regression_gates.get('status', 'pass')} "
         f"candidates={score_distribution.get('candidate_count', 0)} "
         f"budget_limited={budget_fit.get('budget_limited', False)} "
         f"apply=false reasons={reason_text or 'none'}"
@@ -3190,6 +3494,9 @@ def build_parser() -> argparse.ArgumentParser:
     suggest.add_argument("--context-lines", type=int, default=DEFAULT_SUGGEST_CONTEXT_LINES, help="line context around diff/output hits")
     suggest.add_argument("--manifest-out", help="write the suggested build manifest to this relative path under root")
     suggest.add_argument("--adaptive-k", action="store_true", help="include local score/budget top-k advisory metadata without changing the manifest")
+    suggest.add_argument("--adaptive-k-policy", choices=ADAPTIVE_K_POLICIES, default="balanced", help="local adaptive-k recommendation policy used when --adaptive-k is set")
+    suggest.add_argument("--adaptive-k-min-recall-proxy", type=adaptive_k_threshold, default=0.0, help="metadata-only minimum recall proxy gate for --adaptive-k")
+    suggest.add_argument("--adaptive-k-min-precision-proxy", type=adaptive_k_threshold, default=0.0, help="metadata-only minimum precision proxy gate for --adaptive-k")
     suggest.add_argument("--json", action="store_true", help="emit JSON payload")
     auto = sub.add_parser("auto", help="suggest a context pack manifest and build the budgeted pack in one local step")
     auto.add_argument("--root", default=".", help="project root; must not be a symlink")
@@ -3207,6 +3514,9 @@ def build_parser() -> argparse.ArgumentParser:
     auto.add_argument("--no-artifact", action="store_true", help="do not write .context-guard/packs receipt")
     auto.add_argument("--explain", action="store_true", help="include deterministic local selection/build explanation metadata")
     auto.add_argument("--adaptive-k", action="store_true", help="include local score/budget top-k advisory metadata without changing the manifest or pack")
+    auto.add_argument("--adaptive-k-policy", choices=ADAPTIVE_K_POLICIES, default="balanced", help="local adaptive-k recommendation policy used when --adaptive-k is set")
+    auto.add_argument("--adaptive-k-min-recall-proxy", type=adaptive_k_threshold, default=0.0, help="metadata-only minimum recall proxy gate for --adaptive-k")
+    auto.add_argument("--adaptive-k-min-precision-proxy", type=adaptive_k_threshold, default=0.0, help="metadata-only minimum precision proxy gate for --adaptive-k")
     auto.add_argument("--symbol-memory", action="store_true", help="include repo-map derived symbol/graph advisory metadata with exact source verification hints")
     return parser