claude-dev-env 2.19.0 → 2.21.0

package/hooks/advisory/refactor_guard.py

@@ -1,203 +1,309 @@
 #!/usr/bin/env python3
-"""
-Refactor guard - blocks edits that rename/restructure existing code not in the git diff.
+"""Warn about refactors that reach beyond the current Edit change surface."""
 
-Detects when an Edit tool call is modifying existing code (renaming variables,
-functions, restructuring) rather than writing new code or replacing wholesale.
+from __future__ import annotations
 
-Only fires for Edit operations (not Write, which creates/replaces entire files).
-"""
 import json
+import os
 import re
 import subprocess
 import sys
+from collections import Counter
 from pathlib import Path
-from typing import Optional
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.precommit_code_rules_gate_constants import GIT_COMMAND_TIMEOUT_SECONDS
+from hooks_constants.refactor_guard_constants import (
+    ALL_PYTHON_KEYWORDS,
+    CHANGED_SURFACE_MATCH_RATIO,
+    MAXIMUM_REFACTOR_LINE_DELTA,
+    REFACTOR_LINE_DELTA_DIVISOR,
+)
+from hooks_constants.session_edit_stage_gate_constants import GIT_EXECUTABLE_TOKEN
 
 REFACTOR_BYPASS_TOKEN_PATH = Path.home() / ".claude" / ".refactor-bypass-token"
+identifier_join_separator = ", "
 
 
-def get_git_diff_added_lines(file_path: str) -> set[str]:
-    """Get the set of added lines (stripped) from git diff for a file."""
-    added_lines: set[str] = set()
-    try:
-        result = subprocess.run(
-            ["git", "diff", "HEAD", "--", file_path],
-            check=False, capture_output=True,
-            text=True,
-            timeout=5,
-        )
-        for line in result.stdout.split("\n"):
-            if line.startswith("+") and not line.startswith("+++"):
-                added_lines.add(line[1:].strip())
+def _git_query_context(file_path: str) -> tuple[str, str]:
+    """Keep lexical path ownership while Git resolves repository metadata."""
+    target_path = Path(file_path).absolute()
+    return str(target_path.parent), str(target_path)
+
 
-        staged_result = subprocess.run(
-            ["git", "diff", "--staged", "--", file_path],
-            check=False, capture_output=True,
+def _git_environment() -> dict[str, str]:
+    return {
+        each_environment_name: each_environment_value
+        for each_environment_name, each_environment_value in os.environ.items()
+        if not each_environment_name.startswith("GIT_")
+    }
+
+
+def _read_added_lines_from_git(all_git_arguments: tuple[str, ...], file_path: str) -> list[str]:
+    """Return added lines from one Git diff command."""
+    working_directory, absolute_file_path = _git_query_context(file_path)
+    try:
+        completed_process = subprocess.run(
+            [*all_git_arguments, "--", absolute_file_path],
+            check=False,
+            capture_output=True,
             text=True,
-            timeout=5,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=working_directory,
+            env=_git_environment(),
         )
-        for line in staged_result.stdout.split("\n"):
-            if line.startswith("+") and not line.startswith("+++"):
-                added_lines.add(line[1:].strip())
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        return set()
-    return added_lines
+        return []
+    if completed_process.returncode != 0:
+        return []
+    return [
+        each_line[1:].strip()
+        for each_line in completed_process.stdout.splitlines()
+        if each_line.startswith("+") and not each_line.startswith("+++")
+    ]
+
+
+def _get_added_line_occurrences(file_path: str) -> list[str]:
+    all_added_lines = _read_added_lines_from_git((GIT_EXECUTABLE_TOKEN, "diff"), file_path)
+    all_added_lines.extend(
+        _read_added_lines_from_git((GIT_EXECUTABLE_TOKEN, "diff", "--cached"), file_path)
+    )
+    return all_added_lines
+
+
+def get_git_diff_added_lines(file_path: str) -> set[str]:
+    """Return staged and unstaged added lines for a tracked file."""
+    return set(_get_added_line_occurrences(file_path))
 
 
 def is_new_file(file_path: str) -> bool:
-    """Check if file is untracked (entirely new)."""
+    """Return whether Git reports the file as untracked."""
+    working_directory, absolute_file_path = _git_query_context(file_path)
     try:
-        result = subprocess.run(
-            ["git", "ls-files", "--others", "--exclude-standard", "--", file_path],
-            check=False, capture_output=True,
+        completed_process = subprocess.run(
+            [
+                GIT_EXECUTABLE_TOKEN,
+                "ls-files",
+                "--others",
+                "--exclude-standard",
+                "--",
+                absolute_file_path,
+            ],
+            check=False,
+            capture_output=True,
             text=True,
-            timeout=5,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=working_directory,
+            env=_git_environment(),
         )
-        return bool(result.stdout.strip())
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
         return False
+    return completed_process.returncode == 0 and bool(completed_process.stdout.strip())
 
 
 def is_hook_infrastructure(file_path: str) -> bool:
-    """Check if file is a Claude Code hook."""
-    path_lower = file_path.lower().replace("\\", "/")
-    return "/.claude/" in path_lower
+    """Return whether a path belongs to the installed Claude hook tree."""
+    normalized_path = file_path.lower().replace("\\", "/")
+    return "/.claude/" in normalized_path
 
 
 def extract_identifiers(code: str) -> set[str]:
-    """Extract meaningful identifiers (variable/function/class names) from code."""
-    identifier_pattern = re.compile(r'\b([a-zA-Z_][a-zA-Z0-9_]{2,})\b')
-    identifiers = set(identifier_pattern.findall(code))
-    python_keywords = {
-        "def", "class", "return", "import", "from", "if", "elif", "else",
-        "for", "while", "try", "except", "finally", "with", "as", "yield",
-        "raise", "pass", "break", "continue", "and", "or", "not", "in",
-        "is", "lambda", "None", "True", "False", "self", "cls", "async",
-        "await", "global", "nonlocal", "assert", "del", "print", "len",
-        "range", "list", "dict", "set", "str", "int", "float", "bool",
-        "type", "isinstance", "hasattr", "getattr", "setattr", "super",
-        "property", "staticmethod", "classmethod", "abstractmethod",
-        "Optional", "Union", "List", "Dict", "Set", "Tuple", "Any",
-    }
-    return identifiers - python_keywords
-
-
-def is_refactor_edit(old_string: str, new_string: str) -> Optional[str]:
-    """Detect if an edit is a rename/refactor rather than a functional change.
+    """Return meaningful Python identifiers from a code fragment."""
+    all_identifiers = set(re.findall(r"\b([a-zA-Z_][a-zA-Z0-9_]{2,})\b", code))
+    return all_identifiers - ALL_PYTHON_KEYWORDS
+
+
+def _have_similar_words(old_identifier: str, new_identifier: str) -> bool:
+    all_old_words = set(re.findall(r"[a-z]+|[A-Z][a-z]*", old_identifier))
+    all_new_words = set(re.findall(r"[a-z]+|[A-Z][a-z]*", new_identifier))
+    return (
+        bool(all_old_words and all_new_words)
+        and len(all_old_words & all_new_words) >= len(all_old_words) * CHANGED_SURFACE_MATCH_RATIO
+    )
+
+
+def _describe_identifier_changes(
+    all_removed_identifiers: set[str], all_added_identifiers: set[str]
+) -> str | None:
+    all_renamed_identifiers: list[str] = []
+    for each_old_identifier in sorted(all_removed_identifiers):
+        for each_new_identifier in sorted(all_added_identifiers):
+            is_same_spelling = each_old_identifier.lower().replace(
+                "_", ""
+            ) == each_new_identifier.lower().replace("_", "")
+            if is_same_spelling or _have_similar_words(each_old_identifier, each_new_identifier):
+                all_renamed_identifiers.append(f"{each_old_identifier} -> {each_new_identifier}")
+                break
+    if all_renamed_identifiers:
+        return f"Renaming detected: {identifier_join_separator.join(all_renamed_identifiers[:3])}"
+    if len(all_removed_identifiers) > 1 and len(all_added_identifiers) > 1:
+        return (
+            "Multiple identifiers changed with same structure: "
+            f"removed {sorted(all_removed_identifiers)[:3]}, "
+            f"added {sorted(all_added_identifiers)[:3]}"
+        )
+    return None
 
-    Returns a description of the refactor if detected, None otherwise.
-    """
-    old_lines = [line.strip() for line in old_string.strip().split("\n") if line.strip()]
-    new_lines = [line.strip() for line in new_string.strip().split("\n") if line.strip()]
 
-    if not old_lines or not new_lines:
+def is_refactor_edit(old_string: str, new_string: str) -> str | None:
+    """Return a description when an edit preserves structure and changes names."""
+    all_old_lines = [
+        each_line.strip() for each_line in old_string.strip().splitlines() if each_line.strip()
+    ]
+    all_new_lines = [
+        each_line.strip() for each_line in new_string.strip().splitlines() if each_line.strip()
+    ]
+    if not all_old_lines or not all_new_lines:
         return None
-
-    if abs(len(old_lines) - len(new_lines)) > max(len(old_lines) // 2, 3):
+    if abs(len(all_old_lines) - len(all_new_lines)) > max(
+        len(all_old_lines) // REFACTOR_LINE_DELTA_DIVISOR, MAXIMUM_REFACTOR_LINE_DELTA
+    ):
         return None
-
-    old_identifiers = extract_identifiers(old_string)
-    new_identifiers = extract_identifiers(new_string)
-
-    removed_identifiers = old_identifiers - new_identifiers
-    added_identifiers = new_identifiers - old_identifiers
-
-    if not removed_identifiers or not added_identifiers:
+    all_old_identifiers = extract_identifiers(old_string)
+    all_new_identifiers = extract_identifiers(new_string)
+    all_removed_identifiers = all_old_identifiers - all_new_identifiers
+    all_added_identifiers = all_new_identifiers - all_old_identifiers
+    if not all_removed_identifiers or not all_added_identifiers:
         return None
-
-    old_no_ids = old_string
-    new_no_ids = new_string
-    for identifier in old_identifiers | new_identifiers:
-        old_no_ids = old_no_ids.replace(identifier, "ID")
-        new_no_ids = new_no_ids.replace(identifier, "ID")
-
-    old_structure = re.sub(r'\s+', ' ', old_no_ids.strip())
-    new_structure = re.sub(r'\s+', ' ', new_no_ids.strip())
-
-    if old_structure == new_structure:
-        renamed = []
-        for old_id in sorted(removed_identifiers):
-            for new_id in sorted(added_identifiers):
-                if old_id.lower().replace("_", "") == new_id.lower().replace("_", ""):
-                    renamed.append(f"{old_id} -> {new_id}")
-                    break
-                old_words = set(re.findall(r'[a-z]+|[A-Z][a-z]*', old_id))
-                new_words = set(re.findall(r'[a-z]+|[A-Z][a-z]*', new_id))
-                if old_words and new_words and len(old_words & new_words) >= len(old_words) * 0.5:
-                    renamed.append(f"{old_id} -> {new_id}")
-                    break
-
-        if renamed:
-            return f"Renaming detected: {', '.join(renamed[:3])}"
-
-        if len(removed_identifiers) >= 2 and len(added_identifiers) >= 2:
-            return f"Multiple identifiers changed with same structure: removed {sorted(removed_identifiers)[:3]}, added {sorted(added_identifiers)[:3]}"
-
-    return None
+    all_identifiers = all_old_identifiers | all_new_identifiers
+    old_structure = re.sub(r"\s+", " ", _replace_identifiers(old_string, all_identifiers).strip())
+    new_structure = re.sub(r"\s+", " ", _replace_identifiers(new_string, all_identifiers).strip())
+    if old_structure != new_structure:
+        return None
+    return _describe_identifier_changes(all_removed_identifiers, all_added_identifiers)
 
 
-def is_bypass_approved() -> bool:
-    """Check if user explicitly approved a refactor bypass via one-time token file.
+def _replace_identifiers(code: str, all_identifiers: set[str]) -> str:
+    normalized_code = code
+    for each_identifier in all_identifiers:
+        normalized_code = normalized_code.replace(each_identifier, "ID")
+    return normalized_code
 
-    The token file is deleted after a single use, so each refactor
-    requires fresh explicit approval from the user.
-    """
-    if REFACTOR_BYPASS_TOKEN_PATH.exists():
-        REFACTOR_BYPASS_TOKEN_PATH.unlink()
-        return True
-    return False
 
+def _nonempty_stripped_lines(text: str) -> list[str]:
+    return [each_line.strip() for each_line in text.splitlines() if each_line.strip()]
 
-def main() -> None:
-    try:
-        input_data = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
 
-    tool_name = input_data.get("tool_name", "")
-    if tool_name != "Edit":
-        sys.exit(0)
+def is_edit_within_changed_surface(file_path: str, old_string: str) -> bool:
+    """Return whether at least half of the edited lines are current additions."""
+    all_old_lines = _nonempty_stripped_lines(old_string)
+    all_added_lines = _get_added_line_occurrences(file_path)
+    if not all_old_lines or not all_added_lines:
+        return False
+    all_old_line_counts = Counter(all_old_lines)
+    all_added_line_counts = Counter(all_added_lines)
+    matched_occurrence_count = sum(
+        min(each_count, all_added_line_counts[each_line])
+        for each_line, each_count in all_old_line_counts.items()
+    )
+    edited_occurrence_count = sum(all_old_line_counts.values())
+    return matched_occurrence_count / edited_occurrence_count >= CHANGED_SURFACE_MATCH_RATIO
+
+
+def _is_existing_edit_target(file_path: str) -> bool:
+    if not file_path or is_hook_infrastructure(file_path):
+        return False
+    return not is_new_file(file_path)
 
-    if is_bypass_approved():
-        sys.exit(0)
 
-    tool_input = input_data.get("tool_input", {})
-    file_path = tool_input.get("file_path", "")
-    old_string = tool_input.get("old_string", "")
-    new_string = tool_input.get("new_string", "")
+def find_refactor_advisory_description(
+    file_path: str, old_string: str, new_string: str
+) -> str | None:
+    """Return an advisory description for a refactor outside changed lines."""
+    if not _is_existing_edit_target(file_path):
+        return None
+    refactor_description = is_refactor_edit(old_string, new_string)
+    if refactor_description is None:
+        return None
+    if is_edit_within_changed_surface(file_path, old_string):
+        return None
+    return refactor_description
 
-    if not file_path or not old_string or not new_string:
-        sys.exit(0)
 
-    if is_hook_infrastructure(file_path):
-        sys.exit(0)
+def is_refactor_eligible(file_path: str, old_string: str, new_string: str) -> bool:
+    """Return whether an Edit is eligible for the refactor advisory."""
+    return find_refactor_advisory_description(file_path, old_string, new_string) is not None
 
-    if is_new_file(file_path):
-        sys.exit(0)
 
-    refactor_description = is_refactor_edit(old_string, new_string)
-    if not refactor_description:
-        sys.exit(0)
+def is_bypass_approved() -> bool:
+    """Consume the one-use bypass token when the user approved a refactor."""
+    if not REFACTOR_BYPASS_TOKEN_PATH.exists():
+        return False
+    try:
+        REFACTOR_BYPASS_TOKEN_PATH.unlink()
+    except OSError:
+        return False
+    return True
 
-    diff_added_lines = get_git_diff_added_lines(file_path)
 
-    old_lines_stripped = {line.strip() for line in old_string.split("\n") if line.strip()}
-    old_lines_in_diff = old_lines_stripped & diff_added_lines
+def build_refactor_advisory_context(refactor_description: str, file_path: str) -> str:
+    """Build guidance that names the Edit stage and changed-surface rule."""
+    return (
+        f"[HOOK ADVISORY] Refactor guard — {refactor_description} in {file_path}. "
+        "Edit-stage guidance: Only modify lines already changed in the current git diff. "
+        "Ask the user for explicit approval first. If the user approves, "
+        "create the bypass token then retry."
+    )
 
-    if old_lines_in_diff and len(old_lines_in_diff) >= len(old_lines_stripped) * 0.5:
-        sys.exit(0)
 
-    result = {
+def build_refactor_advisory_payload(refactor_description: str, file_path: str) -> dict[str, object]:
+    """Build the standalone allow payload used by the Edit advisory hook."""
+    advisory_context = build_refactor_advisory_context(refactor_description, file_path)
+    return {
+        "systemMessage": advisory_context,
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "allow",
-            "additionalContext": f"[HOOK ADVISORY] Refactor guard — {refactor_description} in {file_path}. Only modify lines already changed in the current git diff. Ask the user for explicit approval first. If the user approves, create the bypass token then retry.",
-        }
+            "additionalContext": advisory_context,
+        },
     }
-    print(json.dumps(result))
+
+
+def _read_hook_input() -> dict[str, object] | None:
+    try:
+        parsed_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, TypeError):
+        return None
+    if not isinstance(parsed_input, dict):
+        return None
+    return parsed_input
+
+
+def _read_edit_fields(payload_by_key: dict[str, object]) -> tuple[str, str, str, str]:
+    raw_tool_name = payload_by_key.get("tool_name")
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    raw_tool_input = payload_by_key.get("tool_input")
+    if not isinstance(raw_tool_input, dict):
+        return tool_name, "", "", ""
+    file_path_field = raw_tool_input.get("file_path")
+    old_string_field = raw_tool_input.get("old_string")
+    new_string_field = raw_tool_input.get("new_string")
+    if not isinstance(file_path_field, str):
+        return tool_name, "", "", ""
+    if not isinstance(old_string_field, str):
+        return tool_name, "", "", ""
+    if not isinstance(new_string_field, str):
+        return tool_name, "", "", ""
+    return tool_name, file_path_field, old_string_field, new_string_field
+
+
+def main() -> None:
+    """Emit an Edit-stage advisory for eligible out-of-surface refactors."""
+    payload_by_key = _read_hook_input()
+    if payload_by_key is None:
+        return
+    tool_name, file_path, old_string, new_string = _read_edit_fields(payload_by_key)
+    if tool_name != "Edit" or is_bypass_approved():
+        return
+    refactor_description = find_refactor_advisory_description(file_path, old_string, new_string)
+    if refactor_description is None:
+        return
+    advisory_payload = build_refactor_advisory_payload(refactor_description, file_path)
+    sys.stdout.write(json.dumps(advisory_payload))
     sys.stdout.flush()
-    sys.exit(0)
 
 
 if __name__ == "__main__":

package/hooks/advisory/refactor_guard_test_support.py

@@ -0,0 +1,46 @@
+"""Shared temporary-repository support for refactor guard tests."""
+
+from __future__ import annotations
+
+import subprocess
+from collections.abc import Generator
+from pathlib import Path
+
+import pytest
+
+
+@pytest.fixture
+def git_repository(tmp_path: Path) -> Generator[Path]:
+    """Create a committed temporary repository for refactor guard tests."""
+    repository_path = tmp_path / "repository"
+    repository_path.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=repository_path, check=True)
+    yield repository_path
+
+
+def commit_file(repository_path: Path, file_path: Path, file_content: str) -> None:
+    """Write and commit one file in a temporary repository."""
+    file_path.write_text(file_content, encoding="utf-8")
+    subprocess.run(["git", "add", str(file_path)], cwd=repository_path, check=True)
+    subprocess.run(
+        [
+            "git",
+            "-c",
+            "user.name=Refactor Guard Test",
+            "-c",
+            "user.email=refactor-guard@example.invalid",
+            "commit",
+            "-q",
+            "-m",
+            "baseline",
+            "--no-verify",
+        ],
+        cwd=repository_path,
+        check=True,
+    )
+
+
+def stage_file(repository_path: Path, file_path: Path, file_content: str) -> None:
+    """Write and stage one file in a temporary repository."""
+    file_path.write_text(file_content, encoding="utf-8")
+    subprocess.run(["git", "add", str(file_path)], cwd=repository_path, check=True)

package/hooks/advisory/test_refactor_guard_advisory.py

@@ -0,0 +1,171 @@
+"""Tests for direct and dispatched refactor guidance."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+ADVISORY_DIRECTORY = Path(__file__).resolve().parent
+HOOK_SCRIPT_PATH = ADVISORY_DIRECTORY / "refactor_guard.py"
+DISPATCHER_SCRIPT_PATH = ADVISORY_DIRECTORY.parent / "blocking" / "pre_tool_use_dispatcher.py"
+if str(ADVISORY_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(ADVISORY_DIRECTORY))
+
+import refactor_guard  # noqa: E402
+from refactor_guard_test_support import commit_file, stage_file  # noqa: E402
+
+
+def _refactor_payload(file_path: Path) -> str:
+    return json.dumps(
+        {
+            "tool_name": "Edit",
+            "tool_input": {
+                "file_path": str(file_path),
+                "old_string": "def calculate_total(amount: int) -> int:\n    return amount",
+                "new_string": "def compute_total(amount: int) -> int:\n    return amount",
+            },
+        }
+    )
+
+
+def _ordinary_edit_payload(file_path: Path) -> str:
+    return json.dumps(
+        {
+            "tool_name": "Edit",
+            "tool_input": {
+                "file_path": str(file_path),
+                "old_string": "return amount",
+                "new_string": "return amount + 1",
+            },
+        }
+    )
+
+
+def _run_hook(
+    script_path: Path, repository_path: Path, payload_text: str
+) -> subprocess.CompletedProcess[str]:
+    environment_by_key = os.environ.copy()
+    environment_by_key["HOME"] = str(repository_path)
+    environment_by_key["USERPROFILE"] = str(repository_path)
+    return subprocess.run(
+        [sys.executable, str(script_path)],
+        cwd=repository_path,
+        input=payload_text,
+        capture_output=True,
+        text=True,
+        env=environment_by_key,
+        check=False,
+    )
+
+
+def test_direct_hook_emits_edit_stage_guidance_for_eligible_refactor(
+    git_repository: Path,
+) -> None:
+    source_path = git_repository / "module.py"
+    commit_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount\n",
+    )
+    stage_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount + 1\n",
+    )
+
+    completed_hook = _run_hook(HOOK_SCRIPT_PATH, git_repository, _refactor_payload(source_path))
+    advisory_payload = json.loads(completed_hook.stdout)
+    hook_specific_output = advisory_payload["hookSpecificOutput"]
+
+    assert hook_specific_output["permissionDecision"] == "allow"
+    assert "Edit-stage" in advisory_payload["systemMessage"]
+    assert "current git diff" in hook_specific_output["additionalContext"]
+    assert str(source_path) in advisory_payload["systemMessage"]
+
+
+def test_direct_hook_stays_silent_for_ordinary_edit(git_repository: Path) -> None:
+    source_path = git_repository / "module.py"
+    commit_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount\n",
+    )
+
+    completed_hook = _run_hook(
+        HOOK_SCRIPT_PATH,
+        git_repository,
+        _ordinary_edit_payload(source_path),
+    )
+
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout == ""
+
+
+def test_direct_hook_stays_silent_for_write_payload(git_repository: Path) -> None:
+    source_path = git_repository / "module.py"
+    commit_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount\n",
+    )
+    write_payload = json.dumps(
+        {
+            "tool_name": "Write",
+            "tool_input": {"file_path": str(source_path), "content": "new content"},
+        }
+    )
+
+    completed_hook = _run_hook(HOOK_SCRIPT_PATH, git_repository, write_payload)
+
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout == ""
+
+
+def test_dispatcher_preserves_edit_stage_guidance(git_repository: Path) -> None:
+    source_path = git_repository / "module.py"
+    matching_test_path = git_repository / "test_module.py"
+    commit_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount\n",
+    )
+    commit_file(
+        git_repository,
+        matching_test_path,
+        "def calculate_total(amount: int) -> int:\n    return amount\n\n"
+        "def test_calculate_total() -> None:\n    assert calculate_total(1) == 1\n",
+    )
+    stage_file(
+        git_repository,
+        source_path,
+        "def calculate_total(amount: int) -> int:\n    return amount + 1\n",
+    )
+
+    completed_dispatch = _run_hook(
+        DISPATCHER_SCRIPT_PATH,
+        git_repository,
+        _refactor_payload(source_path),
+    )
+    dispatcher_payload = json.loads(completed_dispatch.stdout)
+    hook_specific_output = dispatcher_payload["hookSpecificOutput"]
+
+    assert hook_specific_output["permissionDecision"] == "allow", (
+        f"Dispatcher output: {completed_dispatch.stdout!r}; stderr: {completed_dispatch.stderr!r}"
+    )
+    assert "Edit-stage" in dispatcher_payload["systemMessage"]
+    assert "Refactor guard" in dispatcher_payload["systemMessage"]
+
+
+def test_bypass_token_is_consumed_once(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    bypass_token_path = tmp_path / "refactor-bypass-token"
+    monkeypatch.setattr(refactor_guard, "REFACTOR_BYPASS_TOKEN_PATH", bypass_token_path)
+    bypass_token_path.write_text("approved", encoding="utf-8")
+
+    assert refactor_guard.is_bypass_approved()
+    assert not bypass_token_path.exists()
+    assert not refactor_guard.is_bypass_approved()