claude-dev-env 1.93.1 → 1.95.0

package/hooks/blocking/test_pii_prevention_blocker.py

@@ -28,6 +28,7 @@ import pii_prevention_blocker as blocker_module  # noqa: E402
 from pii_prevention_blocker import (  # noqa: E402
     evaluate,
     evaluate_bash_command,
+    evaluate_post_body_texts,
     evaluate_staged_commit,
     evaluate_write_edit_payload,
     extract_git_commit_working_directory,
@@ -903,3 +904,301 @@ def test_git_exe_dash_c_commit_scans_named_repo_not_cwd(tmp_path: Path) -> None:
     assert dash_c_scan is not None
     assert "email" in dash_c_scan
     assert SYNTHETIC_REAL_EMAIL not in dash_c_scan
+
+
+def _add_repository_origin(repository_root: Path, origin_url: str) -> None:
+    subprocess.run(
+        ["git", "remote", "add", "origin", origin_url],
+        cwd=repository_root,
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_exempt_repository_commit_skips_staged_pii_scan(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "https://github.com/ExemptOwner/exempt-repo.git"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is None
+
+
+def test_exempt_repository_matches_ssh_origin_url(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "git@github.com:ExemptOwner/exempt-repo.git"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "exemptowner/EXEMPT-REPO")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is None
+
+
+def test_non_exempt_repository_commit_still_scans_staged_pii(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "https://github.com/OtherOwner/other-repo.git"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_repository_without_origin_is_not_exempt(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_owner_repo_slug_from_https_origin_with_git_suffix() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com/Owner/repo.git"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_from_https_origin_without_git_suffix() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com/Owner/repo"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_from_scp_ssh_origin() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "git@github.com:Owner/repo.git"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_from_ssh_scheme_origin() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "ssh://git@github.com/Owner/repo.git"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_from_trailing_slash_git_suffix() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com/Owner/repo.git/"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_rejects_spoofed_evil_host() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://evil.test/ExemptOwner/exempt-repo.git"
+        )
+        is None
+    )
+
+
+def test_owner_repo_slug_rejects_notgithub_com_host() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://notgithub.com/Owner/repo.git"
+        )
+        is None
+    )
+
+
+def test_owner_repo_slug_rejects_github_com_suffix_host() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com.evil.test/Owner/repo.git"
+        )
+        is None
+    )
+
+
+def test_owner_repo_slug_rejects_invalid_https_port_authority() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com:443.evil.test/Owner/repo.git"
+        )
+        is None
+    )
+
+
+def test_owner_repo_slug_rejects_invalid_ssh_port_authority() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "ssh://git@github.com:22.evil.test/Owner/repo.git"
+        )
+        is None
+    )
+
+
+def test_owner_repo_slug_from_https_origin_with_valid_port() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "https://github.com:443/Owner/repo.git"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_from_ssh_origin_with_valid_port() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "ssh://git@github.com:22/Owner/repo.git"
+        )
+        == "owner/repo"
+    )
+
+
+def test_owner_repo_slug_rejects_path_shaped_origin() -> None:
+    assert (
+        blocker_module._owner_repo_slug_from_origin_url(
+            "C:/repos/ExemptOwner/exempt-repo"
+        )
+        is None
+    )
+
+
+def test_spoofed_origin_host_still_denies_staged_email(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "https://evil.test/ExemptOwner/exempt-repo.git"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_invalid_port_authority_origin_still_denies_staged_email(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root,
+        "https://github.com:443.evil.test/ExemptOwner/exempt-repo.git",
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_path_shaped_origin_still_denies_staged_email(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(repository_root, "C:/repos/ExemptOwner/exempt-repo")
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_trailing_slash_git_suffix_origin_still_exempts(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "https://github.com/ExemptOwner/exempt-repo.git/"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is None
+
+
+def test_ssh_scheme_origin_still_exempts(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    repository_root = tmp_path / "repo"
+    _init_repo_with_staged_email(repository_root)
+    _add_repository_origin(
+        repository_root, "ssh://git@github.com/ExemptOwner/exempt-repo.git"
+    )
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_bash_command(
+        "git commit -m test",
+        working_directory=str(repository_root),
+    )
+    assert deny_reason is None
+
+
+def test_write_still_scans_when_repository_is_exempt(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_write_edit_payload(
+        "Write",
+        {
+            "file_path": "notes.md",
+            "content": f"Reach me at {SYNTHETIC_REAL_EMAIL}",
+        },
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason
+
+
+def test_post_body_still_scans_when_repository_is_exempt(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_PII_EXEMPT_REPOS", "ExemptOwner/exempt-repo")
+    deny_reason = evaluate_post_body_texts(
+        [f"Reach me at {SYNTHETIC_REAL_EMAIL}"]
+    )
+    assert deny_reason is not None
+    assert "email" in deny_reason

package/hooks/blocking/test_plain_language_blocker_allowlist.py

@@ -0,0 +1,184 @@
+"""Tests for the per-project domain-vocabulary allowlist in plain_language_blocker."""
+
+import importlib.util
+import json
+from pathlib import Path
+from types import ModuleType
+
+BLOCKER_PATH = Path(__file__).parent / "plain_language_blocker.py"
+ALLOWLIST_RELATIVE_PATH = Path(".claude") / "plain-language-allow.json"
+ALWAYS_HEAVY_WORD = "utilize"
+
+
+def _load_blocker() -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        "plain_language_blocker_allowlist_under_test", BLOCKER_PATH
+    )
+    assert module_spec is not None and module_spec.loader is not None
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+_BLOCKER = _load_blocker()
+
+
+def _init_repo(root: Path) -> Path:
+    (root / ".git").mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def _write_allowlist(project_root: Path, all_words: list[str]) -> None:
+    allowlist_path = project_root / ALLOWLIST_RELATIVE_PATH
+    allowlist_path.parent.mkdir(parents=True, exist_ok=True)
+    allowlist_path.write_text(json.dumps(all_words), encoding="utf-8")
+
+
+def _write_raw_allowlist(project_root: Path, raw_text: str) -> None:
+    allowlist_path = project_root / ALLOWLIST_RELATIVE_PATH
+    allowlist_path.parent.mkdir(parents=True, exist_ok=True)
+    allowlist_path.write_text(raw_text, encoding="utf-8")
+
+
+def _markdown_write_payload(project_root: Path, prose: str) -> dict[str, object]:
+    document_path = project_root / "docs" / "notes.md"
+    return {
+        "tool_name": "Write",
+        "cwd": str(project_root),
+        "tool_input": {"file_path": str(document_path), "content": prose},
+    }
+
+
+def _ask_user_question_payload(project_root: Path, prose: str) -> dict[str, object]:
+    return {
+        "tool_name": "AskUserQuestion",
+        "cwd": str(project_root),
+        "tool_input": {"questions": [{"question": prose, "options": []}]},
+    }
+
+
+def test_allowlisted_word_passes_in_markdown_write(tmp_path: Path) -> None:
+    prose = "Please submit the release notes."
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["submit"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "submit" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_allowlisted_word_passes_in_ask_user_question(tmp_path: Path) -> None:
+    prose = "Which theme should we identify first?"
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["identify"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _ask_user_question_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _ask_user_question_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "identify" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_non_allowlisted_heavy_word_still_blocked(tmp_path: Path) -> None:
+    _init_repo(tmp_path)
+    _write_allowlist(tmp_path, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, f"Please {ALWAYS_HEAVY_WORD} the cache now.")
+    )
+
+    assert deny_reason is not None and ALWAYS_HEAVY_WORD in deny_reason
+
+
+def test_allowlist_match_is_case_insensitive(tmp_path: Path) -> None:
+    prose = "Please SUBMIT the release notes."
+    project_without_allowlist = _init_repo(tmp_path / "control")
+    project_with_allowlist = _init_repo(tmp_path / "domain")
+    _write_allowlist(project_with_allowlist, ["Submit"])
+
+    control_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, prose)
+    )
+    allowlisted_deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_with_allowlist, prose)
+    )
+
+    assert control_deny_reason is not None and "submit" in control_deny_reason
+    assert allowlisted_deny_reason is None
+
+
+def test_malformed_allowlist_json_is_ignored(tmp_path: Path) -> None:
+    _init_repo(tmp_path)
+    _write_raw_allowlist(tmp_path, "{ this is not valid json ")
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, "Please submit the release notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_in_a_different_project_root_is_not_applied(tmp_path: Path) -> None:
+    project_with_allowlist = _init_repo(tmp_path / "project_a")
+    project_without_allowlist = _init_repo(tmp_path / "project_b")
+    _write_allowlist(project_with_allowlist, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(project_without_allowlist, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_above_the_repo_root_is_not_applied(tmp_path: Path) -> None:
+    _write_allowlist(tmp_path, ["submit"])
+    repository_root = _init_repo(tmp_path / "repo")
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(repository_root, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_allowlist_at_the_repo_root_is_applied(tmp_path: Path) -> None:
+    repository_root = _init_repo(tmp_path / "repo")
+    _write_allowlist(repository_root, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(repository_root, "Please submit the notes.")
+    )
+
+    assert deny_reason is None
+
+
+def test_allowlist_without_a_repo_root_is_not_applied(tmp_path: Path) -> None:
+    _write_allowlist(tmp_path, ["submit"])
+
+    deny_reason = _BLOCKER.evaluate(
+        _markdown_write_payload(tmp_path, "Please submit the notes.")
+    )
+
+    assert deny_reason is not None and "submit" in deny_reason
+
+
+def test_find_banned_terms_skips_allowlisted_terms() -> None:
+    matched_without_allowlist = _BLOCKER.find_banned_terms("Please submit the notes.")
+    matched_with_allowlist = _BLOCKER.find_banned_terms(
+        "Please submit the notes.", frozenset({"submit"})
+    )
+
+    assert any(each_term == "submit" for each_term, _ in matched_without_allowlist)
+    assert all(each_term != "submit" for each_term, _ in matched_with_allowlist)

package/hooks/blocking/test_sensitive_file_protector.py

@@ -0,0 +1,185 @@
+"""Decision tests for the sensitive-file filename guard.
+
+Each case drives the real hook script through its production ``__main__``
+stdin path, feeding it the PreToolUse JSON payload Claude Code sends and
+reading the permission decision back off stdout.
+
+The guard denies a filename that names a live secret or a lock file, and
+steps aside for a placeholders-only committed template (``.env.example``
+and its ``.sample`` / ``.template`` spellings). The template exemption is
+narrow: ``.env.local`` is a ``.env.*`` filename that is not a template, and
+it stays denied.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+HOOK_SCRIPT_PATH = BLOCKING_DIRECTORY / "sensitive_file_protector.py"
+
+WRITE_TOOL_NAME = "Write"
+EDIT_TOOL_NAME = "Edit"
+READ_TOOL_NAME = "Read"
+
+DENY_DECISION = "deny"
+
+PLACEHOLDER_TEMPLATE_BODY = "API_TOKEN=your-token-here\nDATABASE_HOST=localhost\n"
+ORDINARY_SOURCE_BODY = "def add(left: int, right: int) -> int:\n    return left + right\n"
+
+ALL_TEMPLATE_FILENAMES = (
+    ".env.example",
+    ".env.sample",
+    ".env.template",
+    ".ENV.Example",
+    "settings.json.template",
+)
+
+ALL_DENIED_FILENAMES = (
+    ".env",
+    ".env.local",
+    ".env.production",
+    "credentials.json",
+    "secrets.json",
+    "id_rsa",
+    "id_ed25519",
+    "server.pem",
+    "signing.key",
+    "bundle.p12",
+    "bundle.pfx",
+    "package-lock.json",
+    "yarn.lock",
+    "Pipfile.lock",
+    "poetry.lock",
+    "pnpm-lock.yaml",
+    "composer.lock",
+)
+
+ALL_UPPERCASE_DENIED_FILENAMES = (".ENV", "ID_RSA", "CREDENTIALS.JSON", "SERVER.PEM")
+
+ALL_ORDINARY_FILENAMES = ("main.py", "README.md", "settings.json")
+
+
+def _run_hook(tool_name: str, file_path: Path, content: str) -> subprocess.CompletedProcess:
+    payload = json.dumps(
+        {
+            "tool_name": tool_name,
+            "tool_input": {"file_path": str(file_path), "content": content},
+        }
+    )
+    return _run_hook_with_stdin(payload)
+
+
+def _run_hook_with_stdin(stdin_text: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT_PATH)],
+        input=stdin_text,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def _permission_decision(completed: subprocess.CompletedProcess) -> str | None:
+    if not completed.stdout.strip():
+        return None
+    parsed_decision = json.loads(completed.stdout)
+    return parsed_decision["hookSpecificOutput"]["permissionDecision"]
+
+
+def _deny_reason(completed: subprocess.CompletedProcess) -> str:
+    parsed_decision = json.loads(completed.stdout)
+    return parsed_decision["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+@pytest.mark.parametrize("template_filename", ALL_TEMPLATE_FILENAMES)
+def test_template_filename_is_allowed(tmp_path: Path, template_filename: str) -> None:
+    completed = _run_hook(WRITE_TOOL_NAME, tmp_path / template_filename, PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) is None, (
+        f"{template_filename} is a committed template and must not be denied by filename; "
+        f"got stdout {completed.stdout!r}"
+    )
+
+
+@pytest.mark.parametrize("sensitive_filename", ALL_DENIED_FILENAMES)
+def test_sensitive_filename_is_denied(tmp_path: Path, sensitive_filename: str) -> None:
+    completed = _run_hook(WRITE_TOOL_NAME, tmp_path / sensitive_filename, PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == DENY_DECISION, (
+        f"{sensitive_filename} must stay denied; got stdout {completed.stdout!r}"
+    )
+
+
+@pytest.mark.parametrize("uppercase_filename", ALL_UPPERCASE_DENIED_FILENAMES)
+def test_uppercase_sensitive_filename_is_denied(tmp_path: Path, uppercase_filename: str) -> None:
+    completed = _run_hook(WRITE_TOOL_NAME, tmp_path / uppercase_filename, PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == DENY_DECISION, (
+        f"{uppercase_filename} names a secret in an uppercase spelling and must stay denied like "
+        f"its lowercase form; got stdout {completed.stdout!r}"
+    )
+
+
+@pytest.mark.parametrize("ordinary_filename", ALL_ORDINARY_FILENAMES)
+def test_ordinary_source_file_is_allowed(tmp_path: Path, ordinary_filename: str) -> None:
+    completed = _run_hook(WRITE_TOOL_NAME, tmp_path / ordinary_filename, ORDINARY_SOURCE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) is None
+
+
+def test_dot_env_local_deny_reason_names_the_file_and_the_pattern(tmp_path: Path) -> None:
+    completed = _run_hook(WRITE_TOOL_NAME, tmp_path / ".env.local", PLACEHOLDER_TEMPLATE_BODY)
+    assert _permission_decision(completed) == DENY_DECISION
+    deny_reason = _deny_reason(completed)
+    assert ".env.local" in deny_reason
+    assert ".env.*" in deny_reason
+
+
+def test_edit_to_a_template_is_allowed(tmp_path: Path) -> None:
+    completed = _run_hook(EDIT_TOOL_NAME, tmp_path / ".env.example", PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) is None
+
+
+def test_edit_to_a_secrets_file_is_denied(tmp_path: Path) -> None:
+    completed = _run_hook(EDIT_TOOL_NAME, tmp_path / ".env", PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == DENY_DECISION
+
+
+def test_read_tool_is_not_evaluated(tmp_path: Path) -> None:
+    completed = _run_hook(READ_TOOL_NAME, tmp_path / ".env", PLACEHOLDER_TEMPLATE_BODY)
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) is None
+
+
+def test_payload_without_a_file_path_is_allowed() -> None:
+    completed = _run_hook_with_stdin(json.dumps({"tool_name": WRITE_TOOL_NAME, "tool_input": {}}))
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) is None
+
+
+def test_malformed_payload_fails_open() -> None:
+    completed = _run_hook_with_stdin("{not valid json")
+    assert completed.returncode == 0, completed.stderr
+    assert completed.stdout.strip() == ""
+
+
+@pytest.mark.parametrize("trailing_suffix_filename", (".env.example.bak", ".env.template.old", ".env.sample.orig"))
+def test_template_suffix_must_be_last_to_earn_the_exemption(
+    tmp_path: Path, trailing_suffix_filename: str
+) -> None:
+    completed = _run_hook(
+        WRITE_TOOL_NAME, tmp_path / trailing_suffix_filename, PLACEHOLDER_TEMPLATE_BODY
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert _permission_decision(completed) == DENY_DECISION, (
+        f"{trailing_suffix_filename} is a copy of a live secrets file, not a template; "
+        f"only a trailing template suffix earns the exemption, got {completed.stdout!r}"
+    )