claude-dev-env 1.94.0 → 2.0.0

package/hooks/blocking/package_inventory_stale_blocker_parts/inventory_detection.py

@@ -0,0 +1,307 @@
+"""Survey a directory's package inventories and detect a stale omission.
+
+Reads each ``README.md`` / ``CLAUDE.md`` / ``SKILL.md`` beside a file, collects
+the bare filenames they name in backticks, and reports whether a maintained
+inventory omits the file being written.
+"""
+
+import os
+from pathlib import Path
+
+from hooks_constants.package_inventory_stale_blocker_constants import (
+    ALL_EXEMPT_BASENAMES,
+    ALL_EXEMPT_DIRECTORY_NAMES,
+    ALL_INVENTORY_DOCUMENT_NAMES,
+    ALL_PRODUCTION_CODE_EXTENSIONS,
+    ALL_TEST_FILE_MARKERS,
+    BACKTICK_TOKEN_PATTERN,
+    CODE_FENCE_PATTERN,
+    GLOB_METACHARACTER_PATTERN,
+    MAX_INVENTORY_FILE_BYTES,
+    MINIMUM_INVENTORY_ENTRY_COUNT,
+    NON_FILENAME_TOKEN_PATTERN,
+    PYTHON_FILE_EXTENSION,
+    SCRIPTS_SUBDIRECTORY_NAME,
+    SKILL_INVENTORY_DOCUMENT_NAME,
+)
+
+
+def _basename_token(backtick_inner_text: str) -> str | None:
+    """Return the bare filename a backticked token names, when it names one.
+
+    A token names a bare filename when it is a single filename or path token
+    carrying a known file extension; a path keeps only its final segment. A
+    slash-command, a glob/pattern token, a multi-word command-example span, and
+    an extension-less token yield None.
+
+    Args:
+        backtick_inner_text: The text between a backtick pair, stripped.
+
+    Returns:
+        The bare basename the token references, or None when it names no file.
+    """
+    inner_text = backtick_inner_text.strip()
+    if not inner_text or inner_text.startswith("/"):
+        return None
+    if GLOB_METACHARACTER_PATTERN.search(inner_text) is not None:
+        return None
+    if NON_FILENAME_TOKEN_PATTERN.search(inner_text) is not None:
+        return None
+    basename = os.path.basename(inner_text.replace("\\", "/").rstrip("/"))
+    if not basename:
+        return None
+    _, extension = os.path.splitext(basename)
+    if not extension:
+        return None
+    return basename
+
+
+def _lines_outside_code_fences(inventory_content: str) -> list[str]:
+    """Return the inventory lines that sit outside any fenced code block.
+
+    Args:
+        inventory_content: The text of a README.md or CLAUDE.md inventory.
+
+    Returns:
+        The lines that lie outside every code fence, in document order.
+    """
+    live_lines: list[str] = []
+    is_inside_code_fence = False
+    for each_line in inventory_content.splitlines():
+        if CODE_FENCE_PATTERN.match(each_line) is not None:
+            is_inside_code_fence = not is_inside_code_fence
+            continue
+        if is_inside_code_fence:
+            continue
+        live_lines.append(each_line)
+    return live_lines
+
+
+def _line_named_basenames(inventory_line: str) -> set[str]:
+    """Return the bare filenames one inventory line names in backticks.
+
+    Args:
+        inventory_line: One line drawn from outside any code fence.
+
+    Returns:
+        The set of bare basenames the line's backticked tokens name.
+    """
+    line_basenames: set[str] = set()
+    for each_match in BACKTICK_TOKEN_PATTERN.finditer(inventory_line):
+        each_basename = _basename_token(each_match.group(1))
+        if each_basename is not None:
+            line_basenames.add(each_basename)
+    return line_basenames
+
+
+def inventory_named_basenames(inventory_content: str) -> set[str]:
+    """Return every bare filename a package inventory document names in backticks.
+
+    Lines inside a fenced code block are skipped as example text. Each backticked
+    token that names a literal file contributes its basename; a token holding a
+    path contributes its final segment.
+
+    Args:
+        inventory_content: The text of a README.md or CLAUDE.md inventory.
+
+    Returns:
+        The set of bare basenames the inventory names.
+    """
+    named_basenames: set[str] = set()
+    for each_line in _lines_outside_code_fences(inventory_content):
+        named_basenames |= _line_named_basenames(each_line)
+    return named_basenames
+
+
+def _read_inventory_content(inventory_path: Path) -> str | None:
+    """Return the text of an inventory document, or None when it is unreadable.
+
+    Args:
+        inventory_path: The path of the README.md or CLAUDE.md to read.
+
+    Returns:
+        The document text, or None when it is missing, oversized, or undecodable.
+    """
+    try:
+        if inventory_path.stat().st_size > MAX_INVENTORY_FILE_BYTES:
+            return None
+        return inventory_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+class _InventorySurvey:
+    """The inventory documents found beside a file and the files they name.
+
+    Attributes:
+        present_inventory_names: The inventory document basenames present in the
+            directory (``README.md``, ``CLAUDE.md``, and/or ``SKILL.md``).
+        named_basenames: Every bare filename the present inventories name.
+    """
+
+    def __init__(
+        self, all_present_inventory_names: list[str], all_named_basenames: set[str]
+    ) -> None:
+        self.present_inventory_names = all_present_inventory_names
+        self.named_basenames = all_named_basenames
+
+
+def survey_directory_inventories(package_directory: Path) -> _InventorySurvey:
+    """Return the inventory documents beside a file and the basenames they name.
+
+    Args:
+        package_directory: The directory that holds the file being written.
+
+    Returns:
+        The survey pairing the present inventory document names with the union of
+        the basenames they name.
+    """
+    present_inventory_names: list[str] = []
+    named_basenames: set[str] = set()
+    for each_inventory_name in sorted(ALL_INVENTORY_DOCUMENT_NAMES):
+        inventory_path = package_directory / each_inventory_name
+        inventory_content = _read_inventory_content(inventory_path)
+        if inventory_content is None:
+            continue
+        present_inventory_names.append(each_inventory_name)
+        named_basenames |= inventory_named_basenames(inventory_content)
+    return _InventorySurvey(present_inventory_names, named_basenames)
+
+
+def _is_test_file(basename: str) -> bool:
+    """Return whether *basename* names a test file the inventory need not list.
+
+    Args:
+        basename: The bare filename of the file being written.
+
+    Returns:
+        True when the name matches a test-file shape.
+    """
+    if basename.startswith("test_") and basename.endswith(PYTHON_FILE_EXTENSION):
+        return True
+    if basename.endswith("_test" + PYTHON_FILE_EXTENSION):
+        return True
+    return any(each_marker in basename for each_marker in ALL_TEST_FILE_MARKERS)
+
+
+def _is_under_exempt_directory(package_directory: Path) -> bool:
+    """Return whether the file's directory is itself an exempt directory.
+
+    Args:
+        package_directory: The directory that holds the file being written.
+
+    Returns:
+        True when the directory's own name is an exempt directory name.
+    """
+    return package_directory.name in ALL_EXEMPT_DIRECTORY_NAMES
+
+
+def is_inventoried_production_file(file_path: str) -> bool:
+    """Return whether *file_path* is a production file an inventory should name.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        True when the file is one an inventory entry should name.
+    """
+    basename = os.path.basename(file_path)
+    _, extension = os.path.splitext(basename)
+    if extension.lower() not in ALL_PRODUCTION_CODE_EXTENSIONS:
+        return False
+    if basename in ALL_EXEMPT_BASENAMES:
+        return False
+    if _is_test_file(basename):
+        return False
+    return not _is_under_exempt_directory(Path(file_path).resolve().parent)
+
+
+def _sibling_named_basenames(package_directory: Path, all_named_basenames: set[str]) -> set[str]:
+    """Return the named basenames that exist as files in *package_directory*.
+
+    Args:
+        package_directory: The directory that holds the file being written.
+        all_named_basenames: Every bare basename the inventory documents name.
+
+    Returns:
+        The subset of *all_named_basenames* present as a file in the directory.
+    """
+    sibling_basenames: set[str] = set()
+    for each_basename in all_named_basenames:
+        if (package_directory / each_basename).is_file():
+            sibling_basenames.add(each_basename)
+    return sibling_basenames
+
+
+def _parent_skill_inventory(package_directory: Path) -> _InventorySurvey | None:
+    """Return the parent skill ``SKILL.md`` survey for a ``scripts/`` directory.
+
+    A production file landing in a skill's ``scripts/`` directory is governed by
+    the parent ``SKILL.md`` Layout table one level up. Any other directory and a
+    missing or unreadable parent ``SKILL.md`` yield None.
+
+    Args:
+        package_directory: The directory that holds the file being written.
+
+    Returns:
+        The parent ``SKILL.md`` survey, or None when there is none to read.
+    """
+    if package_directory.name != SCRIPTS_SUBDIRECTORY_NAME:
+        return None
+    skill_inventory_path = package_directory.parent / SKILL_INVENTORY_DOCUMENT_NAME
+    inventory_content = _read_inventory_content(skill_inventory_path)
+    if inventory_content is None:
+        return None
+    return _InventorySurvey(
+        [SKILL_INVENTORY_DOCUMENT_NAME], inventory_named_basenames(inventory_content)
+    )
+
+
+def _merged_survey_names(
+    package_directory: Path, survey: _InventorySurvey
+) -> tuple[list[str], set[str]]:
+    """Return the survey names merged with any parent skill ``SKILL.md`` survey.
+
+    Args:
+        package_directory: The directory that holds the file being written.
+        survey: The file's own directory inventory survey.
+
+    Returns:
+        The present inventory names and named basenames, unioned across the
+        directory's own inventories and the parent skill Layout table.
+    """
+    present_inventory_names = list(survey.present_inventory_names)
+    named_basenames = set(survey.named_basenames)
+    parent_skill_survey = _parent_skill_inventory(package_directory)
+    if parent_skill_survey is not None:
+        present_inventory_names += parent_skill_survey.present_inventory_names
+        named_basenames |= parent_skill_survey.named_basenames
+    return present_inventory_names, named_basenames
+
+
+def find_stale_inventory(file_path: str) -> _InventorySurvey | None:
+    """Return the maintained inventory survey a new file is absent from, or None.
+
+    The survey reports a stale inventory only when at least one inventory document
+    is present, those documents name at least the minimum count of on-disk sibling
+    files, and no inventory already names this file's basename.
+
+    Args:
+        file_path: The destination path of the write.
+
+    Returns:
+        The inventory survey when the file is a stale omission, or None.
+    """
+    package_directory = Path(file_path).resolve().parent
+    if not package_directory.is_dir():
+        return None
+    survey = survey_directory_inventories(package_directory)
+    present_inventory_names, named_basenames = _merged_survey_names(package_directory, survey)
+    if not present_inventory_names:
+        return None
+    sibling_basenames = _sibling_named_basenames(package_directory, named_basenames)
+    if len(sibling_basenames) < MINIMUM_INVENTORY_ENTRY_COUNT:
+        return None
+    if os.path.basename(file_path) in named_basenames:
+        return None
+    return _InventorySurvey(present_inventory_names, sibling_basenames)

package/hooks/blocking/package_inventory_stale_blocker_parts/tests/conftest.py

@@ -0,0 +1,10 @@
+"""Put the blocking and hooks directories on sys.path for the parts tests."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parents[2])
+_hooks_directory = str(Path(__file__).resolve().parents[3])
+for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+    if each_bootstrap_directory not in sys.path:
+        sys.path.insert(0, each_bootstrap_directory)

package/hooks/blocking/package_inventory_stale_blocker_parts/tests/test_decision.py

@@ -0,0 +1,38 @@
+"""Tests for the package-inventory blocker decision parts module."""
+
+import json
+
+import pytest
+from package_inventory_stale_blocker_parts import decision as decision_module
+from package_inventory_stale_blocker_parts.config.inventory_blocker_constants import (
+    FILE_FIRST_RETRY_HINT,
+)
+from package_inventory_stale_blocker_parts.decision import (
+    build_block_payload,
+    deny_stale_inventory,
+)
+from package_inventory_stale_blocker_parts.inventory_detection import _InventorySurvey
+
+
+def test_deny_stale_inventory_emits_deny(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(decision_module, "log_hook_block", lambda **each_argument: None)
+    survey = _InventorySurvey(["README.md"], {"alpha.py", "beta.py"})
+    deny_stale_inventory("/pkg/gamma.py", survey)
+    emitted_payload = json.loads(capsys.readouterr().out)
+    assert emitted_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_build_block_payload_names_the_file_and_denies() -> None:
+    survey = _InventorySurvey(["README.md"], {"alpha.py", "beta.py"})
+    block_payload = build_block_payload("/pkg/gamma.py", survey)
+    hook_output = block_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert "gamma.py" in hook_output["permissionDecisionReason"]
+
+
+def test_build_block_payload_appends_retry_hint() -> None:
+    survey = _InventorySurvey(["README.md"], {"alpha.py", "beta.py"})
+    block_payload = build_block_payload("/pkg/gamma.py", survey)
+    assert FILE_FIRST_RETRY_HINT in block_payload["hookSpecificOutput"]["permissionDecisionReason"]

package/hooks/blocking/package_inventory_stale_blocker_parts/tests/test_inventory_detection.py

@@ -0,0 +1,61 @@
+"""Tests for the package-inventory detection parts module."""
+
+from pathlib import Path
+
+from package_inventory_stale_blocker_parts.inventory_detection import (
+    find_stale_inventory,
+    inventory_named_basenames,
+    is_inventoried_production_file,
+    survey_directory_inventories,
+)
+
+README_TWO_FILES = (
+    "# Pipeline\n\n"
+    "| Path | Role |\n"
+    "|---|---|\n"
+    "| `dialer_compose.py` | Composes a dialer strip. |\n"
+    "| `compose_dialer_cli.py` | CLI for the dialer strip. |\n"
+)
+
+
+def _package_with_readme(tmp_path: Path, readme_content: str) -> Path:
+    package_directory = tmp_path / "package_directory"
+    package_directory.mkdir()
+    (package_directory / "README.md").write_text(readme_content, encoding="utf-8")
+    return package_directory
+
+
+def test_inventory_named_basenames_reads_table_cells() -> None:
+    named_basenames = inventory_named_basenames(README_TWO_FILES)
+    assert named_basenames == {"dialer_compose.py", "compose_dialer_cli.py"}
+
+
+def test_survey_directory_inventories_unions_named_files(tmp_path: Path) -> None:
+    package_directory = _package_with_readme(tmp_path, README_TWO_FILES)
+    survey = survey_directory_inventories(package_directory)
+    assert survey.present_inventory_names == ["README.md"]
+    assert survey.named_basenames == {"dialer_compose.py", "compose_dialer_cli.py"}
+
+
+def test_is_inventoried_production_file_accepts_python_module(tmp_path: Path) -> None:
+    assert is_inventoried_production_file(str(tmp_path / "dialer_compose.py")) is True
+
+
+def test_is_inventoried_production_file_rejects_test_file(tmp_path: Path) -> None:
+    assert is_inventoried_production_file(str(tmp_path / "test_dialer.py")) is False
+
+
+def test_find_stale_inventory_reports_omission(tmp_path: Path) -> None:
+    package_directory = _package_with_readme(tmp_path, README_TWO_FILES)
+    for each_basename in ("dialer_compose.py", "compose_dialer_cli.py"):
+        (package_directory / each_basename).write_text("x = 1\n", encoding="utf-8")
+    survey = find_stale_inventory(str(package_directory / "seam_continuity.py"))
+    assert survey is not None
+    assert survey.named_basenames == {"dialer_compose.py", "compose_dialer_cli.py"}
+
+
+def test_find_stale_inventory_allows_named_file(tmp_path: Path) -> None:
+    package_directory = _package_with_readme(tmp_path, README_TWO_FILES)
+    for each_basename in ("dialer_compose.py", "compose_dialer_cli.py"):
+        (package_directory / each_basename).write_text("x = 1\n", encoding="utf-8")
+    assert find_stale_inventory(str(package_directory / "compose_dialer_cli.py")) is None

package/hooks/blocking/pii_payload_scan.py

@@ -12,30 +12,39 @@ from __future__ import annotations
 import sys
 from pathlib import Path
 
-_blocking_directory = str(Path(__file__).resolve().parent)
-_hooks_directory = str(Path(__file__).resolve().parent.parent)
-if _blocking_directory not in sys.path:
-    sys.path.insert(0, _blocking_directory)
-if _hooks_directory not in sys.path:
-    sys.path.insert(0, _hooks_directory)
-
-from pii_scanner import (  # noqa: E402
-    PiiFinding,
-    is_path_exempt_from_pii_scan,
-    scan_text_for_pii,
-)
-
-from hooks_constants.multi_edit_reconstruction import edits_for_tool  # noqa: E402
-from hooks_constants.pii_prevention_constants import (  # noqa: E402
-    ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
-    CORRECTIVE_MESSAGE_FOOTER,
-    CORRECTIVE_MESSAGE_HEADER,
-    EDIT_TOOL_NAME,
-    FINDING_LINE_TEMPLATE,
-    MESSAGE_LINE_SEPARATOR,
-    MULTI_EDIT_TOOL_NAME,
-    WRITE_TOOL_NAME,
-)
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+    from pii_prevention_blocker_parts.repository_exemption import (
+        repository_allowlisted_values,
+    )
+    from pii_scanner import (
+        PiiFinding,
+        is_path_exempt_from_pii_scan,
+        scan_text_for_pii,
+    )
+    from precommit_code_rules_gate import resolve_repository_root
+
+    from hooks_constants.local_identity import pii_allowlisted_values_by_repository
+    from hooks_constants.multi_edit_reconstruction import edits_for_tool
+    from hooks_constants.pii_prevention_constants import (
+        ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+        CORRECTIVE_MESSAGE_FOOTER,
+        CORRECTIVE_MESSAGE_HEADER,
+        EDIT_TOOL_NAME,
+        FINDING_LINE_TEMPLATE,
+        MESSAGE_LINE_SEPARATOR,
+        MULTI_EDIT_TOOL_NAME,
+        WRITE_TOOL_NAME,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "pii_payload_scan: cannot import its sibling modules; "
+        "ensure the blocking and hooks directories are importable."
+    ) from import_error
 
 
 def build_deny_reason(all_findings: list[PiiFinding], gate_surface: str) -> str:
@@ -64,6 +73,20 @@ def build_deny_reason(all_findings: list[PiiFinding], gate_surface: str) -> str:
     return message_line_separator.join(all_lines)
 
 
+def _new_strings_from_edits(
+    tool_name: str, all_tool_input: dict[str, object]
+) -> list[str]:
+    """Return each non-empty ``new_string`` from an Edit/MultiEdit payload."""
+    all_texts: list[str] = []
+    for each_edit in edits_for_tool(tool_name, all_tool_input):
+        if not isinstance(each_edit, dict):
+            continue
+        new_string = each_edit.get("new_string", "")
+        if isinstance(new_string, str) and new_string:
+            all_texts.append(new_string)
+    return all_texts
+
+
 def _collect_write_edit_texts(
     tool_name: str, all_tool_input: dict[str, object]
 ) -> tuple[str, list[str]]:
@@ -77,33 +100,87 @@ def _collect_write_edit_texts(
             return file_path, [write_content]
         return file_path, []
     if tool_name in (EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME):
-        all_texts: list[str] = []
-        for each_edit in edits_for_tool(tool_name, all_tool_input):
-            if not isinstance(each_edit, dict):
-                continue
-            new_string = each_edit.get("new_string", "")
-            if isinstance(new_string, str) and new_string:
-                all_texts.append(new_string)
-        return file_path, all_texts
+        return file_path, _new_strings_from_edits(tool_name, all_tool_input)
     return file_path, []
 
 
-def _first_findings_in_texts(all_texts: list[str]) -> list[PiiFinding]:
+def _findings_after_allowlist(
+    text: str, all_allowlisted_values: frozenset[str]
+) -> list[PiiFinding]:
+    """Return PII findings in *text* whose matched text is not allowlisted."""
+    return [
+        each_finding
+        for each_finding in scan_text_for_pii(text)
+        if each_finding.matched_text not in all_allowlisted_values
+    ]
+
+
+def _first_findings_in_texts(
+    all_texts: list[str], all_allowlisted_values: frozenset[str] = frozenset()
+) -> list[PiiFinding]:
     for each_text in all_texts:
-        all_findings = scan_text_for_pii(each_text)
+        all_findings = _findings_after_allowlist(each_text, all_allowlisted_values)
         if all_findings:
             return all_findings
     return []
 
 
+def _existing_ancestor_directory(file_path: str) -> str | None:
+    """Return the nearest existing ancestor directory of *file_path*, or None.
+
+    PreToolUse runs before Write creates nested parents, so the immediate parent
+    may not exist yet; git resolution needs a directory that is already on disk.
+    """
+    starting_directory = Path(file_path).parent
+    for each_ancestor in (starting_directory, *starting_directory.parents):
+        if each_ancestor.exists():
+            return str(each_ancestor)
+    return None
+
+
+def _write_path_allowlisted_values(file_path: str) -> frozenset[str]:
+    """Return the exact values allowlisted for the repository *file_path* sits in.
+
+    ::
+
+        no path, or no allowlist configured  ->  frozenset()  (no git call)
+        path inside an allowlisted repo tree  ->  that repo's frozenset of values
+
+    Args:
+        file_path: The write target path whose repository keys the allowlist.
+
+    Returns:
+        The exact values the repository allows past the scan, or an empty set.
+    """
+    if not file_path:
+        return frozenset()
+    if not pii_allowlisted_values_by_repository():
+        return frozenset()
+    resolution_directory = _existing_ancestor_directory(file_path)
+    if resolution_directory is None:
+        return frozenset()
+    repository_root = resolve_repository_root(resolution_directory)
+    if repository_root is None:
+        return frozenset()
+    return repository_allowlisted_values(repository_root)
+
+
 def evaluate_write_edit_payload(
-    tool_name: str, all_tool_input: dict[str, object]
+    tool_name: str,
+    all_tool_input: dict[str, object],
+    all_allowlisted_values: frozenset[str] = frozenset(),
 ) -> str | None:
     """Return a deny reason when Write/Edit/MultiEdit content carries PII.
 
+    A value in the target repository's PII allowlist is dropped from the
+    findings, so a write under that repository's tree may carry it. Repository
+    resolution for that allowlist runs only after a raw PII hit.
+
     Args:
         tool_name: The intercepted tool name.
         all_tool_input: The tool input mapping.
+        all_allowlisted_values: Extra exact values allowed past the scan,
+            unioned with the target repository's own allowlist.
 
     Returns:
         Deny reason text, or None when the write is clean or out of scope.
@@ -111,23 +188,42 @@ def evaluate_write_edit_payload(
     if tool_name not in ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES:
         return None
     file_path, all_texts = _collect_write_edit_texts(tool_name, all_tool_input)
-    all_findings = _first_findings_in_texts(all_texts)
-    if not all_findings:
-        return None
-    gate_surface = f"file write ({file_path or 'unknown path'})"
-    return build_deny_reason(all_findings, gate_surface)
+    resolved_allowlisted_values: frozenset[str] | None = None
+    for each_text in all_texts:
+        all_raw_findings = scan_text_for_pii(each_text)
+        if not all_raw_findings:
+            continue
+        if resolved_allowlisted_values is None:
+            resolved_allowlisted_values = (
+                all_allowlisted_values | _write_path_allowlisted_values(file_path)
+            )
+        all_findings = [
+            each_finding
+            for each_finding in all_raw_findings
+            if each_finding.matched_text not in resolved_allowlisted_values
+        ]
+        if all_findings:
+            gate_surface = f"file write ({file_path or 'unknown path'})"
+            return build_deny_reason(all_findings, gate_surface)
+    return None
 
 
-def evaluate_post_body_texts(all_body_texts: list[str]) -> str | None:
+def evaluate_post_body_texts(
+    all_body_texts: list[str],
+    all_allowlisted_values: frozenset[str] = frozenset(),
+) -> str | None:
     """Return a deny reason when any durable post body carries PII.
 
     Args:
         all_body_texts: Body strings extracted from a gh or MCP post tool.
+        all_allowlisted_values: Exact values the caller's repository allows;
+            a finding matching one is not a finding. Callers that pass
+            nothing keep every post fully scanned.
 
     Returns:
         Deny reason text, or None when every body is clean.
     """
-    all_findings = _first_findings_in_texts(all_body_texts)
+    all_findings = _first_findings_in_texts(all_body_texts, all_allowlisted_values)
     if not all_findings:
         return None
     return build_deny_reason(all_findings, "durable GitHub post body")