@ictechgy/context-guard 0.4.11 → 0.4.13

package/plugins/context-guard/bin/context-guard-rewrite-bash

@@ -19,6 +19,7 @@ import sys
 SHELL_OPERATOR_TOKENS = {";", ";;", ";&", ";;&", "&", "&&", "|", "||", "<", ">", "<<", ">>", "<>", "(", ")"}
 SHELL_OPERATOR_CHARS = frozenset(";&|<>()")
 ENV_ASSIGNMENT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=.*")
+SAFE_PIPE_FILTER_BASENAMES = frozenset({"cat", "head", "tail", "wc", "sort", "uniq"})
 WRAPPER_BASENAMES = frozenset({
     "trim_command_output.py",
     "context-guard-trim-output",
@@ -164,6 +165,59 @@ def split_single_safe_command(command: str) -> list[str] | None:
     return argv
 
 
+def split_safe_sanitizer_pipeline(command: str) -> list[list[str]] | None:
+    """Return argv segments for a narrow read-only pipeline safe to sanitizer-wrap.
+
+    Compound search/diff/log commands are useful in practice (`git diff | cat`,
+    `rg token . | head`), but arbitrary shell operators can branch output to
+    files/network or change control flow before the sanitizer sees it.  This
+    helper therefore allows only plain `|` pipelines where the first segment is
+    sanitizer-worthy and every later segment is a simple stdout filter.  It
+    intentionally rejects redirection, here-doc/string, `tee`, `curl`, `&&`,
+    command substitution, and other shell syntax.
+    """
+    if not command.strip():
+        return None
+    if any(char in command for char in "\n\r\t`"):
+        return None
+    if "$(" in command or "${" in command:
+        return None
+    try:
+        lexer = shlex.shlex(command, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        tokens = list(lexer)
+    except ValueError:
+        return None
+    if "|" not in tokens:
+        return None
+
+    segments: list[list[str]] = [[]]
+    for token in tokens:
+        is_operator = token in SHELL_OPERATOR_TOKENS or (
+            any(char in SHELL_OPERATOR_CHARS for char in token)
+            and all(char in SHELL_OPERATOR_CHARS for char in token)
+        )
+        if is_operator:
+            if token != "|":
+                return None
+            if not segments[-1]:
+                return None
+            segments.append([])
+            continue
+        if any(char in token for char in "`\n\r\t"):
+            return None
+        if "$(" in token or "${" in token:
+            return None
+        segments[-1].append(token)
+    if not segments or not segments[-1] or len(segments) < 2:
+        return None
+    if not (is_sanitizable_output_command(segments[0]) or is_log_streaming_command(segments[0])):
+        return None
+    if not all(is_safe_pipe_filter(segment) for segment in segments[1:]):
+        return None
+    return segments
+
+
 def command_basename(command: str) -> str:
     return os.path.basename(command)
 
@@ -214,6 +268,70 @@ def npm_script_args(rest: list[str]) -> list[str]:
     return rest[i:]
 
 
+def _filter_args_are_stdin_only(first: str, args: list[str]) -> bool:
+    """Accept small, option-only filter argv forms that do not name files."""
+    if first == "cat":
+        return not args
+    long_no_value_options = {
+        "head": set(),
+        "tail": set(),
+        "wc": {"--bytes", "--chars", "--lines", "--words"},
+        "sort": {"--ignore-leading-blanks", "--dictionary-order", "--ignore-case", "--general-numeric-sort", "--human-numeric-sort", "--numeric-sort", "--reverse", "--unique"},
+        "uniq": {"--count", "--repeated", "--unique", "--ignore-case"},
+    }.get(first, set())
+    short_no_value_chars = {
+        "head": set(),
+        "tail": {"f", "F", "r"},
+        "wc": {"c", "m", "l", "w"},
+        "sort": {"b", "d", "f", "g", "h", "n", "r", "u"},
+        "uniq": {"c", "d", "u", "i"},
+    }.get(first, set())
+    value_options = {"-n", "--lines", "-c", "--bytes"} if first in {"head", "tail"} else set()
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            return i == len(args) - 1
+        if arg.startswith("--") and "=" in arg:
+            name, value = arg.split("=", 1)
+            if name not in value_options:
+                return False
+            if not re.fullmatch(r"[+-]?\d+[KkMmGg]?", value):
+                return False
+            i += 1
+            continue
+        if arg in value_options:
+            if i + 1 >= len(args):
+                return False
+            if not re.fullmatch(r"[+-]?\d+[KkMmGg]?", args[i + 1]):
+                return False
+            i += 2
+            continue
+        if arg in long_no_value_options:
+            i += 1
+            continue
+        if arg.startswith("--"):
+            return False
+        if arg.startswith("-") and arg != "-":
+            if not set(arg[1:]).issubset(short_no_value_chars):
+                return False
+            i += 1
+            continue
+        if arg.startswith("-"):
+            return False
+        return False
+    return True
+
+
+def is_safe_pipe_filter(argv: list[str]) -> bool:
+    if not argv:
+        return False
+    first = command_basename(argv[0])
+    if first not in SAFE_PIPE_FILTER_BASENAMES:
+        return False
+    return _filter_args_are_stdin_only(first, argv[1:])
+
+
 def is_noisy_command(argv: list[str]) -> bool:
     argv = strip_env_prefix(argv)
     if not argv:
@@ -423,6 +541,16 @@ def build_sanitized_command(wrapper: str, command: str) -> str:
     return shlex.join(wrapped_argv)
 
 
+def print_updated_command(wrapped: str) -> None:
+    response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "updatedInput": {"command": wrapped},
+        }
+    }
+    print(json.dumps(response, ensure_ascii=False))
+
+
 def main() -> int:
     if any(arg in {"-h", "--help"} for arg in sys.argv[1:]):
         print("ContextGuard helper: context-guard-rewrite-bash")
@@ -450,11 +578,25 @@ def main() -> int:
     argv = split_single_safe_command(command)
     if not argv:
         if unparseable_command_needs_sanitizer(command):
-            deny(
-                "Search/diff/log command contains shell operators that cannot be safely rewritten. "
-                "Run the command through context-guard-sanitize-output explicitly, simplify it, or set "
-                f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
-            )
+            safe_pipeline = split_safe_sanitizer_pipeline(command)
+            if safe_pipeline is None:
+                deny(
+                    "Search/diff/log command contains shell operators that are not in ContextGuard's "
+                    "read-only pipe allowlist. Simplify to a plain pipeline ending in cat/head/tail/wc/sort/uniq, "
+                    "run context-guard-sanitize-output explicitly after review, or set "
+                    f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
+                )
+                return 0
+            wrapper = find_wrapper("sanitize")
+            if wrapper is None:
+                deny(
+                    "Search/diff/log command blocked because it contains shell operators and "
+                    "context-guard-sanitize-output is not installed next to context-guard-rewrite-bash. "
+                    "Install the sanitizer or set "
+                    f"{FAIL_OPEN_ENV}=1 to run unsanitized intentionally."
+                )
+                return 0
+            print_updated_command(build_sanitized_command(wrapper, command))
             return 0
         print_noop()
         return 0
@@ -490,13 +632,7 @@ def main() -> int:
         print("{}")
         return 0
 
-    response = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "updatedInput": {"command": wrapped},
-        }
-    }
-    print(json.dumps(response, ensure_ascii=False))
+    print_updated_command(wrapped)
     return 0
 
 

package/plugins/context-guard/bin/context-guard-sanitize-output

@@ -49,9 +49,17 @@ PRIVATE_KEY_END_RE = re.compile(
 AUTH_HEADER_RE = re.compile(
     r"(?i)^(?P<prefix>\s*(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:Proxy-)?Authorization\s*:\s*).+$"
 )
+COOKIE_HEADER_RE = re.compile(
+    r"(?i)^(?P<prefix>\s*(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:Set-)?Cookie\s*:\s*).+$"
+)
+SESSION_SECRET_KEY = (
+    r"(?:session(?:[_-]?(?:id|token))?|sessionid|sid|jsessionid|"
+    r"csrf(?:[_-]?token)?|xsrf(?:[_-]?token)?)"
+)
 SECRET_KEY = (
     r"[A-Za-z0-9_.-]*(?:api[_-]?key|apikey|token|secret|password|passwd|pwd|"
     r"private[_-]?key|access[_-]?key|client[_-]?secret)[A-Za-z0-9_.-]*"
+    rf"|{SESSION_SECRET_KEY}"
     r"|AWS_ACCESS_KEY_ID|AWS_SECRET_ACCESS_KEY|AWS_SESSION_TOKEN|"
     r"GOOGLE_APPLICATION_CREDENTIALS|AZURE_CLIENT_SECRET"
 )
@@ -61,11 +69,48 @@ INLINE_QUOTED_SECRET_ASSIGNMENT_RE = re.compile(
     rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*)"
     rf"(?P<quote>[\"'])(?P<value>(?:\\.|(?!(?P=quote)).)*)(?P=quote)(?P<tail>[^\s,;}}\]]*)"
 )
+CODE_IDENTIFIER = r"[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*"
+CALL_ARGUMENT_CHUNK = r"(?:[^()\"'\n;]+|\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*'|\([^()]*\))*"
+INLINE_UNQUOTED_CALL_SECRET_ASSIGNMENT_RE = re.compile(
+    rf"(?i)(?P<lead>^|[\s;{{\[,])"
+    rf"(?P<prefix>(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:export\s+)?"
+    rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*)"
+    rf"(?P<value>(?![\"']){CODE_IDENTIFIER}\({CALL_ARGUMENT_CHUNK}\))"
+)
+SECRET_IDENTIFIER_PART = (
+    r"(?:[A-Za-z_$][A-Za-z0-9_$]*(?:api_?key|apikey|token|secret|password|passwd|pwd|"
+    r"private_?key|access_?key|client_?secret|sessionid|session_id|session_token|"
+    r"csrf_token|xsrf_token)[A-Za-z0-9_$]*|session|sid|csrf|xsrf)"
+)
+FALLBACK_SECRET_OPERAND = rf"(?:[A-Za-z_$][A-Za-z0-9_$]*\.)*{SECRET_IDENTIFIER_PART}"
+INLINE_UNQUOTED_FALLBACK_SECRET_ASSIGNMENT_RE = re.compile(
+    rf"(?i)(?P<lead>^|[\s;{{\[,])"
+    rf"(?P<prefix>(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:export\s+)?"
+    rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*)"
+    rf"(?P<value>(?![\"']|\[REDACTED\])"
+    rf"[^;\n]*?(?:\bor\b|\|\||\?\?|\belse\b|\?[^:\n;]*:)\s*"
+    rf"(?:[\"'](?:\\.|[^\"'\\])*[\"']|{FALLBACK_SECRET_OPERAND})[^;\n]*)"
+)
+INLINE_UNQUOTED_BRACKETED_SECRET_ASSIGNMENT_RE = re.compile(
+    rf"(?i)(?P<lead>^|[\s;{{\[,])"
+    rf"(?P<prefix>(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:export\s+)?"
+    rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*)"
+    rf"(?P<value>(?![\"']|\[REDACTED\])"
+    rf"[^\s,;}}\]]*(?:\([^;\n]*?\)|\{{[^;\n]*?\}}|\[[^;\n]*?\])[^\s,;}}\]]*)"
+)
 INLINE_UNQUOTED_SECRET_ASSIGNMENT_RE = re.compile(
     rf"(?i)(?P<lead>^|[\s;{{\[,])"
     rf"(?P<prefix>(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:export\s+)?"
     rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*)"
-    rf"(?P<value>[^\s,;}}\]]+)"
+    rf"(?P<value>(?![\"']|\[REDACTED\])[^\s,;}}\]]+)"
+)
+UNQUOTED_MULTILINE_SECRET_ASSIGNMENT_RE = re.compile(
+    rf"(?i)(?:^|[\s;{{\[,])"
+    rf"(?:(?:[^:\n]+):\d+(?::\d+)?:)?\s*(?:[+-]\s*)?(?:export\s+)?"
+    rf"[\"']?(?:{SECRET_KEY})[\"']?\s*[:=]\s*(?P<value>(?![\"']).*)$"
+)
+CONTINUATION_OPERATOR_RE = re.compile(
+    r"(?i)(?:\\|\|\||&&|\?\?|[+*/%&|^?,]|\?|:|\bor\b|\band\b|\belse\b)\s*(?://.*|#.*)?$"
 )
 URL_LIKE_RE = re.compile(r"\b[A-Za-z][A-Za-z0-9+.-]*://[^\s]+")
 URL_SECRET_PARAM_RE = re.compile(rf"(?i)([?&#;](?:{SECRET_KEY})=)[^\s?&#;]+")
@@ -80,6 +125,43 @@ SAFE_UNQUOTED_VALUES = {
     "undefined",
 }
 IDENTIFIER_CHAIN_RE = re.compile(r"^[A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)+$")
+SAFE_ENV_LOOKUP_CALL_RE = re.compile(r"^(?:os\.getenv|os\.environ\.get)\(\s*[\"'][A-Za-z0-9_.-]{1,80}[\"']\s*\)$")
+SAFE_RE_COMPILE_CALL_RE = re.compile(r"^re\.compile\([^;\n]*\)$")
+SAFE_CODE_EXPRESSION_CALL_RE = re.compile(rf"^{CODE_IDENTIFIER}\(\s*(?:{CODE_IDENTIFIER}(?:\s*,\s*{CODE_IDENTIFIER})*)?\s*\)$")
+GETTER_CALL_RE = re.compile(rf"^{CODE_IDENTIFIER}\.get\(\s*[\"'](?P<key>[A-Za-z0-9_.-]{{1,80}})[\"']\s*\)$")
+CAMEL_ACRONYM_BOUNDARY_RE = re.compile(r"(?<=[A-Z])(?=[A-Z][a-z])")
+CAMEL_WORD_BOUNDARY_RE = re.compile(r"(?<=[a-z0-9])(?=[A-Z])")
+SAFE_GETTER_KEY_NAMES = {
+    "access_key",
+    "access_token",
+    "api_key",
+    "apikey",
+    "auth",
+    "authorization",
+    "aws_access_key_id",
+    "aws_secret_access_key",
+    "aws_session_token",
+    "azure_client_secret",
+    "client_id",
+    "client_secret",
+    "cookie",
+    "credential",
+    "credentials",
+    "csrf",
+    "google_application_credentials",
+    "jwt",
+    "password",
+    "passwd",
+    "private_key",
+    "pwd",
+    "refresh_token",
+    "secret",
+    "session",
+    "session_id",
+    "sessionid",
+    "sid",
+    "token",
+}
 INLINE_PATTERNS: tuple[tuple[re.Pattern[str], str], ...] = (
     (re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+"), "[REDACTED]"),
     (re.compile(r"(?i)\bBasic\s+[A-Za-z0-9._~+/=-]+"), "[REDACTED]"),
@@ -171,20 +253,33 @@ def cap_line(line: str, max_line_chars: int) -> tuple[str, bool]:
     return body[:keep] + marker + newline, True
 
 
+def normalize_getter_key(key: str) -> str:
+    key = CAMEL_ACRONYM_BOUNDARY_RE.sub("_", key)
+    key = CAMEL_WORD_BOUNDARY_RE.sub("_", key)
+    key = re.sub(r"[_.-]+", "_", key)
+    return re.sub(r"_+", "_", key).strip("_").lower()
+
+
+def is_safe_getter_key(key: str) -> bool:
+    return normalize_getter_key(key) in SAFE_GETTER_KEY_NAMES
+
+
 def should_redact_unquoted_secret_value(line: str, match: re.Match[str]) -> bool:
     value = match.group("value").strip()
+    prefix = match.group("prefix")
     if not value:
         return False
     if value.lower() in SAFE_UNQUOTED_VALUES:
         return False
     if IDENTIFIER_CHAIN_RE.match(value):
         return False
-    end = match.end("value")
-    if end < len(line) and line[end] in "([{":
-        # Likely a function call or expression (`api_key = os.getenv(...)`);
-        # preserve it so Claude can still reason about code flow.
+    if SAFE_ENV_LOOKUP_CALL_RE.match(value) or SAFE_RE_COMPILE_CALL_RE.match(value):
         return False
-    if any(ch in value for ch in "()[]{}"):
+    getter_match = GETTER_CALL_RE.match(value)
+    if re.search(r"\s[:=]\s*$", prefix) and (
+        SAFE_CODE_EXPRESSION_CALL_RE.match(value)
+        or (getter_match is not None and is_safe_getter_key(getter_match.group("key")))
+    ):
         return False
     return True
 
@@ -218,6 +313,9 @@ def redact_secret_assignments(line: str) -> tuple[str, bool]:
         return f"{match.group('lead')}{match.group('prefix')}[REDACTED]"
 
     line = INLINE_QUOTED_SECRET_ASSIGNMENT_RE.sub(quoted_repl, line)
+    line = INLINE_UNQUOTED_FALLBACK_SECRET_ASSIGNMENT_RE.sub(unquoted_repl, line)
+    line = INLINE_UNQUOTED_CALL_SECRET_ASSIGNMENT_RE.sub(unquoted_repl, line)
+    line = INLINE_UNQUOTED_BRACKETED_SECRET_ASSIGNMENT_RE.sub(unquoted_repl, line)
     line = INLINE_UNQUOTED_SECRET_ASSIGNMENT_RE.sub(unquoted_repl, line)
     return line, redacted
 
@@ -257,6 +355,54 @@ def detect_multiline_secret_assignment(line: str) -> str | None:
     return None
 
 
+def expression_bracket_delta(text: str) -> int:
+    delta = 0
+    quote: str | None = None
+    escaped = False
+    for char in text:
+        if quote is not None:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+            continue
+        if char in {"'", '"'}:
+            quote = char
+        elif char in "([{":
+            delta += 1
+        elif char in ")}]":
+            delta -= 1
+    return delta
+
+
+def ends_with_continuation_operator(text: str) -> bool:
+    return bool(CONTINUATION_OPERATOR_RE.search(text.rstrip()))
+
+
+def detect_multiline_secret_expression(line: str) -> int | None:
+    marker = UNQUOTED_MULTILINE_SECRET_ASSIGNMENT_RE.search(line)
+    if marker is None:
+        return None
+    value = marker.group("value").strip()
+    if not value:
+        return 0
+    delta = expression_bracket_delta(value)
+    if delta > 0:
+        return delta
+    if ends_with_continuation_operator(value):
+        return max(delta, 0)
+    return None
+
+
+def update_multiline_secret_expression_state(line: str, depth: int) -> int | None:
+    next_depth = max(0, depth + expression_bracket_delta(line))
+    if next_depth == 0 and not ends_with_continuation_operator(line):
+        return None
+    return next_depth
+
+
 def private_key_state_after_line(line: str) -> bool | None:
     """Return updated private-key state for a line, or None when no marker appears."""
     if PRIVATE_KEY_BEGIN_RE.search(line):
@@ -277,6 +423,7 @@ class LineSanitizer:
         self.show_paths = show_paths
         self.in_private_key_block = False
         self.multiline_secret_quote: str | None = None
+        self.multiline_secret_expression_depth: int | None = None
         self.redactions = 0
 
     def sanitize(self, raw_line: str) -> tuple[str, bool]:
@@ -309,6 +456,12 @@ class LineSanitizer:
                 self.in_private_key_block = False
             return self._finish(diff_prefix + "[REDACTED PRIVATE KEY BLOCK]\n", redacted)
 
+        if self.multiline_secret_expression_depth is not None:
+            self.multiline_secret_expression_depth = update_multiline_secret_expression_state(
+                line, self.multiline_secret_expression_depth
+            )
+            return self._finish(diff_prefix + "[REDACTED MULTILINE SECRET]\n", True)
+
         multiline_quote = detect_multiline_secret_assignment(line)
         if multiline_quote is not None:
             self.multiline_secret_quote = multiline_quote
@@ -323,11 +476,21 @@ class LineSanitizer:
                 self.in_private_key_block = True
             return self._finish(diff_prefix + "[REDACTED PRIVATE KEY BLOCK]\n", redacted)
 
+        expression_depth = detect_multiline_secret_expression(line)
+        if expression_depth is not None:
+            self.multiline_secret_expression_depth = expression_depth
+            return self._finish(diff_prefix + "[REDACTED MULTILINE SECRET]\n", True)
+
         new_line, count = AUTH_HEADER_RE.subn(r"\g<prefix>[REDACTED]", line)
         if count:
             redacted = True
             line = new_line
 
+        new_line, count = COOKIE_HEADER_RE.subn(r"\g<prefix>[REDACTED]", line)
+        if count:
+            redacted = True
+            line = new_line
+
         line, assignment_redacted = redact_secret_assignments(line)
         if assignment_redacted:
             redacted = True

package/plugins/context-guard/bin/context-guard-setup

@@ -2210,6 +2210,25 @@ def backup_existing(path: Path) -> Path | None:
     return backup
 
 
+def rollback_restore_guidance(settings_path: Path, backup_path: Path | None, original_existed: bool) -> str:
+    if backup_path is not None:
+        return (
+            "Restore only with a no-follow, symlink-safe copy that opens the backup and target parent "
+            "without following links, then atomically replaces the target; do not use generic shell "
+            f"copy/delete commands on this mutable target. Backup: {backup_path}. Target: {settings_path}."
+        )
+    if original_existed:
+        return (
+            "No backup path was recorded; inspect the target with no-follow file operations before any "
+            f"manual recovery. Do not use generic shell copy/delete commands on this mutable target: {settings_path}."
+        )
+    return (
+        "The target did not exist before setup. If cleanup is required, verify the target and every parent "
+        "without following symlinks and remove only the verified regular file; do not use generic shell "
+        f"delete commands on this mutable target: {settings_path}."
+    )
+
+
 def write_rollback_record(
     *,
     root: Path,
@@ -2237,11 +2256,8 @@ def write_rollback_record(
         "target_path": str(settings_path),
         "backup_path": str(backup_path) if backup_path else None,
         "original_existed": original_existed,
-        "restore": (
-            f"cp {shlex.quote(str(backup_path))} {shlex.quote(str(settings_path))}"
-            if backup_path
-            else f"rm -f {shlex.quote(str(settings_path))}"
-        ),
+        "restore": rollback_restore_guidance(settings_path, backup_path, original_existed),
+        "restore_requires_no_follow": True,
     }
     atomic_write(rollback_path, json.dumps(record, indent=2, sort_keys=True) + "\n", 0o600)
     return rollback_id, rollback_path

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

@@ -87,6 +87,8 @@ class Candidate:
     index: int
     score: float = 0.0
     rank: int = 0
+    schema_bytes: int = 0
+    parameter_terms: frozenset[str] | None = None
 
 
 def fail(message: str) -> NoReturn:
@@ -276,7 +278,15 @@ def tool_schema_from_dict(raw: dict[str, Any], *, fallback_name: str | None = No
         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)
+    return Candidate(
+        name=name,
+        server=cap_text(server, MAX_LABEL_CHARS) if server else None,
+        description=description,
+        schema=schema,
+        index=index,
+        schema_bytes=byte_len_json(schema),
+        parameter_terms=frozenset(terms(" ".join(collect_parameter_text(schema)))),
+    )
 
 
 def normalize_catalog(raw: Any) -> list[Candidate]:
@@ -362,7 +372,11 @@ def score_candidate(candidate: Candidate, query_terms: set[str]) -> float:
         return 0.0
     name_terms = terms(candidate.name)
     desc_terms = terms(candidate.description)
-    parameter_terms = terms(" ".join(collect_parameter_text(candidate.schema)))
+    parameter_terms = (
+        set(candidate.parameter_terms)
+        if candidate.parameter_terms is not None
+        else 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)
@@ -379,14 +393,38 @@ 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.append(Candidate(
+            cand.name,
+            cand.server,
+            cand.description,
+            cand.schema,
+            cand.index,
+            score_candidate(cand, query_terms),
+            0,
+            schema_bytes=cand.schema_bytes,
+            parameter_terms=cand.parameter_terms,
+        ))
     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))
+        ranked.append(Candidate(
+            cand.name,
+            cand.server,
+            cand.description,
+            cand.schema,
+            cand.index,
+            cand.score,
+            rank,
+            schema_bytes=cand.schema_bytes,
+            parameter_terms=cand.parameter_terms,
+        ))
     return ranked
 
 
+def candidate_schema_bytes(cand: Candidate) -> int:
+    return cand.schema_bytes if cand.schema_bytes > 0 else byte_len_json(cand.schema)
+
+
 def normalized_link_target(parent: Path, raw_target: str) -> Path:
     target = Path(raw_target)
     if not target.is_absolute():
@@ -707,7 +745,7 @@ def build_payload(receipt_id: str, ranked: list[Candidate], query: str, redactio
                 "description": cand.description,
                 "score": cand.score,
                 "rank": cand.rank,
-                "schema_bytes": byte_len_json(cand.schema),
+                "schema_bytes": candidate_schema_bytes(cand),
                 "schema": cand.schema,
             }
             for cand in ranked
@@ -739,7 +777,7 @@ def retrieval_command(receipt_id: str, *, store_dir: str, tool_name: str | None
 
 
 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)
+    schema_size = candidate_schema_bytes(cand)
     record: dict[str, Any] = {
         "name": cand.name,
         "server": cand.server,
@@ -765,7 +803,7 @@ def deferred_tool_record(cand: Candidate, receipt_id: str, *, store_dir: str) ->
         "score": cand.score,
         "rank": cand.rank,
         "description": cand.description,
-        "schema_bytes": byte_len_json(cand.schema),
+        "schema_bytes": candidate_schema_bytes(cand),
         "reason": "deferred_after_core_top",
         "retrieval": retrieval_command(receipt_id, store_dir=store_dir, tool_name=cand.name),
     }
@@ -1008,9 +1046,9 @@ def defer_report(args: argparse.Namespace) -> str:
         store_dir=args.store_dir,
         namespace_top=namespace_top,
     )
-    all_schema_bytes = sum(byte_len_json(cand.schema) for cand in ranked)
-    listed_deferred_schema_bytes = sum(byte_len_json(cand.schema) for cand in deferred_candidates)
-    total_deferred_schema_bytes = sum(byte_len_json(cand.schema) for cand in ranked[core_top:])
+    all_schema_bytes = sum(candidate_schema_bytes(cand) for cand in ranked)
+    listed_deferred_schema_bytes = sum(candidate_schema_bytes(cand) for cand in deferred_candidates)
+    total_deferred_schema_bytes = sum(candidate_schema_bytes(cand) for cand in ranked[core_top:])
     tool_stub_report_bytes = byte_len_json(core_tools) + byte_len_json(deferred_tools)
     all_schema_tokens = proxy_tokens(all_schema_bytes)
     inline_core_schema_tokens = proxy_tokens(core_schema_bytes)