claude-dev-env 2.30.0 → 2.31.0

package/.agents/agents/pr-description-writer.md

@@ -1,6 +1,6 @@
 ---
 name: pr-description-writer
-description: "Optional agent that writes factual pull request titles, descriptions, and comments in plain illustrative language from the current diff."
+description: "Writes factual pull request titles, descriptions, and comments in plain illustrative language from the current diff. The `pr_description_writer_gate` PreToolUse hook requires a spawn of this agent before `gh pr create`."
 tools: Read,Grep,Glob,Bash
 ---
 

package/.agents/skills/e-simplify/SKILL.md

@@ -25,7 +25,7 @@ Triggers: `/e-simplify` on the current diff (or a PR/branch/path passed as an ar
 
 ## The process
 
-`/simplify → 4 cleanup agents in parallel → apply the fixes`
+`/simplify → up to 4 cleanup agents in parallel → apply the fixes`
 
 You are improving the quality of the changed code, not hunting for bugs. Review
 it for reuse, simplification, efficiency, and altitude issues, then fix what you
@@ -40,13 +40,25 @@ include the working-tree changes in scope — the review often runs before the
 commit. If a PR number, branch name, or file path was passed as an argument,
 review that target instead. Treat this diff as the review scope.
 
-### Phase 1 — Review (4 cleanup agents in parallel)
+**Diff-size cap.** Run `git diff --shortstat` on the same range Phase 0 used
+to get the diff, and add its insertions and deletions for the changed-line
+count. Default ceiling: 400 changed lines for one run — a tunable default the
+user may adjust. Above the ceiling, narrow the target first — a subdirectory,
+a package, or one file path — and review that narrowed target. Do not launch
+Phase 1 over a diff above the ceiling.
 
-Launch **4 independent review agents** via the Agent tool, all in a
-single message so they run concurrently. Pass each agent the diff and one of
-the four angles below. Each returns its findings with `file`, `line`, a
-one-line `summary`, and the concrete cost (what is duplicated, wasted, or
-harder to maintain).
+### Phase 1 — Review (up to 4 cleanup agents in parallel)
+
+**Lens cap.** Four lenses is the ceiling, not the floor. Default split — also
+tunable — by the `git diff --shortstat` changed-line count from Phase 0:
+under 100 changed lines, run 2 lenses (reuse and simplification); at 100
+changed lines or above, and under the diff-size cap, run all 4 lenses.
+
+Launch the review agents for the lenses in scope for this run — 2 or 4 by the
+cap above — via the Agent tool, all in a single message so they run
+concurrently. Pass each agent the diff and one of the angles below. Each
+returns its findings with `file`, `line`, a one-line `summary`, and the
+concrete cost (what is duplicated, wasted, or harder to maintain).
 
 #### Reuse
 
@@ -79,7 +91,7 @@ special cases.
 
 ### Phase 2 — Apply the fixes
 
-Wait for all four agents to complete, dedup findings that point at the same
+Wait for every launched agent to complete, dedup findings that point at the same
 line or mechanism, and fix each remaining one directly. Skip any finding whose
 fix would change intended behavior, require changes well outside the reviewed
 diff, or that you judge to be a false positive — note the skip rather than

package/AGENTS.md

@@ -1 +1,7 @@
+Use positive, present-focused prose.
 
+State what should be done, what something does, what was done, or what needs to be done.
+
+Include only information directly relevant to the immediate task or remaining work.
+
+Use direct outcome-focused wording. Omit filler, failed attempts, alternatives considered, and process narration.

package/_shared/pr-loop/scripts/code_rules_gate_parts/tests/test_enforcer_loading.py

@@ -1,9 +1,13 @@
 """Behavioral tests for the enforcer_loading parts module."""
 
+import subprocess
+import sys
 from pathlib import Path
 
 from code_rules_gate_parts import enforcer_loading
 
+_SCRIPTS_DIRECTORY = Path(__file__).resolve().parents[2]
+
 
 def test_resolve_claude_dev_env_root_finds_enforcer_bearing_root() -> None:
     resolved_root = enforcer_loading.resolve_claude_dev_env_root(Path(__file__))
@@ -15,3 +19,36 @@ def test_load_validate_content_for_full_gate_returns_callable_passing_a_clean_mo
     clean_module = '"""Clean module."""\n\n\ndef ping() -> str:\n    return "pong"\n'
     issues = validate_content(clean_module, "sample.py", "")
     assert issues == []
+
+
+def test_load_validate_content_for_full_gate_survives_a_cold_sys_modules_cache() -> None:
+    """This test guards sys.modules caching, not the import path itself.
+
+    A module the enforcer imports directly (not through the hooks_constants
+    package this loader already resets) can stay cached in sys.modules from
+    an earlier test in the same pytest session, so a broken import path can
+    still read as working once some earlier test already imported the
+    module successfully. A fresh interpreter carries no such cache.
+
+    This does not prove the import path resolves in every layout the gate
+    is loaded from -- a projected layout missing a dependency file is a
+    separate failure this test cannot see, because this process still runs
+    against the real repository tree where every dependency already exists
+    on disk. That coverage lives in test_bugteam_code_rules_gate.py, whose
+    fixture copies a deliberately narrower file set.
+    """
+    probe_script = (
+        "from code_rules_gate_parts.enforcer_loading import "
+        "load_validate_content_for_full_gate\n"
+        "load_validate_content_for_full_gate()\n"
+        "print('ENFORCER_LOAD_OK')\n"
+    )
+    completed_process = subprocess.run(
+        [sys.executable, "-c", probe_script],
+        cwd=str(_SCRIPTS_DIRECTORY),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed_process.returncode == 0, completed_process.stderr
+    assert "ENFORCER_LOAD_OK" in completed_process.stdout

package/bin/install.prune.test.mjs

@@ -62,7 +62,7 @@ const RETIRED_HOOK_RELATIVE_SEGMENTS = ['blocking', 'retired_gate.py'];
 const USER_HOOK_COMMAND = 'python3 my_own_gate.py --user-authored';
 const RETIRED_HOOK_EVENT_TYPE = 'PreToolUse';
 const DROPPED_HOOK_EVENT_TYPE = 'PreCompact';
-const RETIRED_HOOK_MATCHER = 'Write|Edit|MultiEdit';
+const DISPATCHER_HOOK_COMMAND_SEGMENT = 'pre_tool_use_dispatcher.py';
 const UNMANAGED_SIBLING_DIRECTORY = 'my-notes';
 const NESTED_SKILL_DIRECTORY = 'foo';
 const NESTED_SKILL_FILE_SEGMENTS = [NESTED_SKILL_DIRECTORY, 'scripts', 'a.py'];
@@ -909,7 +909,9 @@ function seedRetiredManagedHook(sandbox) {
     const lookalikeHookCommand = `python3 "${retiredHookPath.replace(/\\/g, '/')}.bak"`;
     const settings = readSettings(sandbox.claudeDirectory);
     const liveGroup = settings.hooks[RETIRED_HOOK_EVENT_TYPE]
-        .find(group => group.matcher === RETIRED_HOOK_MATCHER);
+        .find(group => group.hooks.some(
+            hook => hook.command.includes(DISPATCHER_HOOK_COMMAND_SEGMENT),
+        ));
     liveGroup.hooks.push({ type: 'command', command: retiredHookCommand });
     liveGroup.hooks.push({ type: 'command', command: USER_HOOK_COMMAND });
     liveGroup.hooks.push({ type: 'command', command: lookalikeHookCommand });

package/docs/CODE_RULES.md

@@ -119,3 +119,14 @@ If you already have the data, don't fetch it again.
 3. **Changed-line scope filters only the report.** `defer_scope_to_caller` and the changed-line set decide which found violations block. Scope filters findings after every check in the roster already ran; it adds or removes no check.
 
 `hooks/hooks_constants/validation_phase_constants.py` is the single source for all three axes: the phase names (`EDIT_LANE_PHASE`, `FULL_GATE_PHASE`), the full-gate-only roster (`ALL_FULL_GATE_ONLY_CHECK_NAMES`), and the hook-infrastructure edit-lane roster (`ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES`).
+
+## 11.6 LANE ASSIGNMENT IS BY SCOPE
+
+Scope assigns the lane. A check that reads a file other than the target runs on the full gate. Every other check runs on both lanes.
+
+Hook-infrastructure targets run three checks in the edit lane — `check_same_file_inline_duplicate_body`, `check_zero_payload_function_alias`, `check_unanchored_command_dispatch` — and the whole roster on the full gate. `ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES` holds that set.
+
+Two surfaces report on the roster, and each reports a specific thing:
+
+- `hooks/validators/hook_timing_harness.py` builds a `Write` payload against a target that already holds content. `_contents_for_validation` returns `None` for that payload, so the harness times interpreter start and hook dispatch. Time an `Edit` payload against a real file to measure the checks.
+- `~/.claude/logs/hook-blocks.log` records the denials raised by fixtures in `test_code_rules_enforcer_*.py` and by the timing harness's default target.

package/hooks/advisory/migration_safety_advisor.py

@@ -4,24 +4,48 @@
 import json
 import re
 import sys
+from pathlib import Path
+
+try:
+    _hooks_dir = str(Path(__file__).resolve().parent.parent)
+    if _hooks_dir not in sys.path:
+        sys.path.insert(0, _hooks_dir)
+
+    from hooks_constants.migration_safety_advisor_constants import (
+        MULTI_EDIT_TOOL_NAME,
+    )
+    from hooks_constants.multi_edit_reconstruction import joined_new_strings
+except ImportError as import_error:
+    raise ImportError(
+        "migration_safety_advisor: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
 
 MIGRATION_PATH_PATTERN = re.compile(r"[/\\]migrations[/\\]\d{4}_\w+\.py$")
 UNSAFE_OPERATIONS = ["RemoveField", "RenameField", "DeleteModel", "RenameModel"]
 
 
+def _resolve_content(tool_name: str, all_tool_input: dict) -> str:
+    """Return the text a Write, Edit, or MultiEdit payload introduces."""
+    if tool_name == MULTI_EDIT_TOOL_NAME:
+        return joined_new_strings(all_tool_input)
+    return all_tool_input.get("content", "") or all_tool_input.get("new_string", "")
+
+
 def main() -> None:
     try:
         hook_input = json.load(sys.stdin)
     except json.JSONDecodeError:
         sys.exit(0)
 
+    tool_name = hook_input.get("tool_name", "")
     tool_input = hook_input.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 
     if not MIGRATION_PATH_PATTERN.search(file_path):
         sys.exit(0)
 
-    content = tool_input.get("content", "") or tool_input.get("new_string", "")
+    content = _resolve_content(tool_name, tool_input)
     found_unsafe = [op for op in UNSAFE_OPERATIONS if op in content]
 
     if found_unsafe:

package/hooks/advisory/refactor_guard.py

@@ -11,18 +11,26 @@ import sys
 from collections import Counter
 from pathlib import Path
 
-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
+try:
+    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.multi_edit_reconstruction import edits_for_tool
+    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
+except ImportError as import_error:
+    raise ImportError(
+        "refactor_guard: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
 
 REFACTOR_BYPASS_TOKEN_PATH = Path.home() / ".claude" / ".refactor-bypass-token"
 identifier_join_separator = ", "
@@ -187,10 +195,9 @@ def _nonempty_stripped_lines(text: str) -> list[str]:
     return [each_line.strip() for each_line in text.splitlines() if each_line.strip()]
 
 
-def is_edit_within_changed_surface(file_path: str, old_string: str) -> bool:
+def _lines_within_changed_surface(old_string: str, all_added_lines: list[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)
@@ -203,6 +210,12 @@ def is_edit_within_changed_surface(file_path: str, old_string: str) -> bool:
     return matched_occurrence_count / edited_occurrence_count >= CHANGED_SURFACE_MATCH_RATIO
 
 
+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_added_lines = _get_added_line_occurrences(file_path)
+    return _lines_within_changed_surface(old_string, all_added_lines)
+
+
 def _is_existing_edit_target(file_path: str) -> bool:
     if not file_path or is_hook_infrastructure(file_path):
         return False
@@ -290,20 +303,74 @@ def _read_edit_fields(payload_by_key: dict[str, object]) -> tuple[str, str, str,
     return tool_name, file_path_field, old_string_field, new_string_field
 
 
+def _refactor_advisory_description_within_surface(
+    all_added_lines: list[str],
+    old_string: str,
+    new_string: str,
+) -> str | None:
+    """Return an advisory description for one edit, given the file's added lines."""
+    refactor_description = is_refactor_edit(old_string, new_string)
+    if refactor_description is None:
+        return None
+    if _lines_within_changed_surface(old_string, all_added_lines):
+        return None
+    return refactor_description
+
+
+def _multi_edit_refactor_advisory_description(
+    payload_by_key: dict[str, object],
+) -> tuple[str, str] | None:
+    """Return the (file_path, description) pair for the first eligible edit in a MultiEdit."""
+    raw_tool_input = payload_by_key.get("tool_input")
+    if not isinstance(raw_tool_input, dict):
+        return None
+    file_path_field = raw_tool_input.get("file_path")
+    file_path = file_path_field if isinstance(file_path_field, str) else ""
+    if not file_path:
+        return None
+    if not _is_existing_edit_target(file_path):
+        return None
+    all_added_lines = _get_added_line_occurrences(file_path)
+    for each_edit in edits_for_tool("MultiEdit", raw_tool_input):
+        if not isinstance(each_edit, dict):
+            continue
+        old_string_field = each_edit.get("old_string")
+        new_string_field = each_edit.get("new_string")
+        if not isinstance(old_string_field, str) or not isinstance(new_string_field, str):
+            continue
+        refactor_description = _refactor_advisory_description_within_surface(
+            all_added_lines, old_string_field, new_string_field
+        )
+        if refactor_description is not None:
+            return file_path, refactor_description
+    return None
+
+
+def _emit_advisory(file_path: str, refactor_description: str) -> None:
+    advisory_payload = build_refactor_advisory_payload(refactor_description, file_path)
+    sys.stdout.write(json.dumps(advisory_payload))
+    sys.stdout.flush()
+
+
 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():
+    if is_bypass_approved():
+        return
+    if tool_name == "MultiEdit":
+        multi_edit_result = _multi_edit_refactor_advisory_description(payload_by_key)
+        if multi_edit_result is not None:
+            _emit_advisory(*multi_edit_result)
+        return
+    if tool_name != "Edit":
         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()
+    _emit_advisory(file_path, refactor_description)
 
 
 if __name__ == "__main__":

package/hooks/advisory/test_migration_safety_advisor.py

@@ -7,8 +7,6 @@ import subprocess
 import sys
 from pathlib import Path
 
-import pytest
-
 
 _ADVISORY_DIRECTORY = Path(__file__).resolve().parent
 _HOOKS_DIRECTORY = _ADVISORY_DIRECTORY.parent
@@ -59,6 +57,7 @@ def _build_control_payload(tool_name: str, file_path: Path, content: str) -> dic
 
 
 def _prepare_fresh_test_pair(migration_path: Path) -> None:
+    """Write a migration module and its paired test file."""
     migration_path.parent.mkdir(parents=True)
     migration_path.write_text("operations = []\n", encoding="utf-8")
     test_path = migration_path.with_name(f"test_{migration_path.stem}.py")
@@ -104,12 +103,12 @@ def test_dispatcher_surfaces_migration_warning_for_edit(tmp_path: Path) -> None:
     assert "MIGRATION SAFETY" in _text_field(dispatched_payload, "systemMessage")
 
 
-@pytest.mark.parametrize("tool_name", ("Write", "MultiEdit"))
-def test_dispatcher_keeps_migration_advisor_edit_only(tmp_path: Path, tool_name: str) -> None:
+def test_dispatcher_keeps_migration_advisor_write_excluded(tmp_path: Path) -> None:
+    """Write stays out of the migration advisor's roster; only Edit and MultiEdit reach it."""
     migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
     _prepare_fresh_test_pair(migration_path)
     payload = _build_control_payload(
-        tool_name,
+        "Write",
         migration_path,
         'operations = [migrations.RemoveField("name")]',
     )
@@ -118,3 +117,88 @@ def test_dispatcher_keeps_migration_advisor_edit_only(tmp_path: Path, tool_name:
     serialized_payload = json.dumps(dispatched_payload or {})
 
     assert "MIGRATION SAFETY" not in serialized_payload
+
+
+def test_dispatcher_extends_migration_advisor_to_multi_edit(tmp_path: Path) -> None:
+    """A MultiEdit reaches the migration advisor the same way an Edit does."""
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    _prepare_fresh_test_pair(migration_path)
+    payload = _build_control_payload(
+        "MultiEdit",
+        migration_path,
+        'operations = [migrations.RemoveField("name")]',
+    )
+
+    dispatched_payload = _run_hook(_DISPATCHER_SCRIPT, payload)
+    assert dispatched_payload is not None
+    serialized_payload = json.dumps(dispatched_payload)
+
+    assert "MIGRATION SAFETY" in serialized_payload
+
+
+def _build_multi_edit_payload(
+    file_path: Path, all_edits: list[dict[str, str]]
+) -> dict[str, object]:
+    return {
+        "tool_name": "MultiEdit",
+        "tool_input": {"file_path": str(file_path), "edits": all_edits},
+    }
+
+
+def test_standalone_advisor_warns_for_unsafe_operation_in_second_multi_edit(
+    tmp_path: Path,
+) -> None:
+    """An unsafe operation in the second edit of a MultiEdit is caught, not only the first.
+
+    migration_safety_advisor has no tool_name gate today: it reads
+    tool_input.get("new_string"), a key a MultiEdit payload never carries at
+    the top level. Widening its roster entry alone would silently do
+    nothing on a real MultiEdit call.
+    """
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    payload = _build_multi_edit_payload(
+        migration_path,
+        [
+            {"old_string": "operations = []", "new_string": "operations = [migrations.AddField()]"},
+            {
+                "old_string": "migrations.AddField()",
+                "new_string": 'migrations.AddField(), migrations.RemoveField("name")',
+            },
+        ],
+    )
+
+    advisory_payload = _run_hook(_ADVISOR_SCRIPT, payload)
+    assert advisory_payload is not None
+    permission_fields = _permission_fields(advisory_payload)
+
+    assert permission_fields["permissionDecision"] == "allow"
+    assert "RemoveField" in _text_field(permission_fields, "additionalContext")
+
+
+def test_standalone_advisor_reads_a_write_payloads_content_field(tmp_path: Path) -> None:
+    """_resolve_content's non-MultiEdit branch reads a Write payload's "content" key."""
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    payload: dict[str, object] = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": str(migration_path),
+            "content": 'operations = [migrations.RemoveField("name")]',
+        },
+    }
+
+    advisory_payload = _run_hook(_ADVISOR_SCRIPT, payload)
+    assert advisory_payload is not None
+    assert "RemoveField" in _text_field(
+        _permission_fields(advisory_payload), "additionalContext"
+    )
+
+
+def test_standalone_advisor_is_silent_for_a_clean_multi_edit(tmp_path: Path) -> None:
+    migration_path = tmp_path / "billing" / "migrations" / "0002_remove_name.py"
+    payload = _build_multi_edit_payload(
+        migration_path,
+        [{"old_string": "operations = []", "new_string": "operations = [migrations.AddField()]"}],
+    )
+
+    advisory_payload = _run_hook(_ADVISOR_SCRIPT, payload)
+    assert advisory_payload is None

package/hooks/advisory/test_refactor_guard.py

@@ -0,0 +1,87 @@
+"""Unit tests for refactor_guard's MultiEdit reconstruction, run in-process.
+
+test_refactor_guard_advisory.py and test_refactor_guard_eligibility.py already
+cover this hook end to end through real git fixtures; these tests exercise
+``_multi_edit_refactor_advisory_description`` directly against a target path
+outside any git repository, where the underlying git commands fail closed and
+return no added lines, so a qualifying rename is eligible without fixture setup.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+try:
+    _ADVISORY_DIRECTORY = Path(__file__).resolve().parent
+    if str(_ADVISORY_DIRECTORY) not in sys.path:
+        sys.path.insert(0, str(_ADVISORY_DIRECTORY))
+
+    import refactor_guard
+except ImportError as import_error:
+    raise ImportError(
+        "test_refactor_guard: cannot import its sibling modules; "
+        "ensure the advisory directory is importable."
+    ) from import_error
+
+
+def _multi_edit_payload(file_path: str, all_edits: list[dict[str, str]]) -> dict[str, object]:
+    return {
+        "tool_name": "MultiEdit",
+        "tool_input": {"file_path": file_path, "edits": all_edits},
+    }
+
+
+def test_multi_edit_reports_the_first_eligible_rename(tmp_path: Path) -> None:
+    """A rename in the second edit is reported, even though the first edit is ordinary."""
+    target_path = str(tmp_path / "module.py")
+    payload = _multi_edit_payload(
+        target_path,
+        [
+            {"old_string": "return amount", "new_string": "return amount + 1"},
+            {
+                "old_string": "def calculate_total(amount):\n    return amount",
+                "new_string": "def compute_total(amount):\n    return amount",
+            },
+        ],
+    )
+
+    result = refactor_guard._multi_edit_refactor_advisory_description(payload)
+
+    assert result is not None
+    reported_path, description = result
+    assert reported_path == target_path
+    assert "calculate_total" in description
+    assert "compute_total" in description
+
+
+def test_multi_edit_scans_past_two_ordinary_edits_to_the_third(tmp_path: Path) -> None:
+    """The loop over edit pairs reaches the third pair, not only the first two."""
+    target_path = str(tmp_path / "module.py")
+    payload = _multi_edit_payload(
+        target_path,
+        [
+            {"old_string": "return amount", "new_string": "return amount + 1"},
+            {"old_string": "return amount + 1", "new_string": "return amount + 2"},
+            {
+                "old_string": "def calculate_total(amount):\n    return amount + 2",
+                "new_string": "def compute_total(amount):\n    return amount + 2",
+            },
+        ],
+    )
+
+    result = refactor_guard._multi_edit_refactor_advisory_description(payload)
+
+    assert result is not None
+    _reported_path, description = result
+    assert "compute_total" in description
+
+
+def test_multi_edit_returns_none_when_no_edit_qualifies(tmp_path: Path) -> None:
+    target_path = str(tmp_path / "module.py")
+    payload = _multi_edit_payload(
+        target_path,
+        [{"old_string": "return amount", "new_string": "return amount + 1"}],
+    )
+
+    assert refactor_guard._multi_edit_refactor_advisory_description(payload) is None

package/hooks/advisory/test_refactor_guard_advisory.py

@@ -19,6 +19,8 @@ if str(ADVISORY_DIRECTORY) not in sys.path:
 import refactor_guard  # noqa: E402
 from refactor_guard_test_support import commit_file, stage_file  # noqa: E402
 
+pytestmark = pytest.mark.usefixtures("ephemeral_exempt_off")
+
 
 def _refactor_payload(file_path: Path) -> str:
     return json.dumps(
@@ -127,6 +129,7 @@ def test_direct_hook_stays_silent_for_write_payload(git_repository: Path) -> Non
 
 
 def test_dispatcher_preserves_edit_stage_guidance(git_repository: Path) -> None:
+    """A red step (staged, uncommitted test) plus a staged refactor still allows."""
     source_path = git_repository / "module.py"
     matching_test_path = git_repository / "test_module.py"
     commit_file(
@@ -134,7 +137,7 @@ def test_dispatcher_preserves_edit_stage_guidance(git_repository: Path) -> None:
         source_path,
         "def calculate_total(amount: int) -> int:\n    return amount\n",
     )
-    commit_file(
+    stage_file(
         git_repository,
         matching_test_path,
         "def calculate_total(amount: int) -> int:\n    return amount\n\n"
@@ -169,3 +172,71 @@ def test_bypass_token_is_consumed_once(tmp_path: Path, monkeypatch: pytest.Monke
     assert refactor_guard.is_bypass_approved()
     assert not bypass_token_path.exists()
     assert not refactor_guard.is_bypass_approved()
+
+
+def _multi_edit_payload(file_path: Path, all_edits: list[dict[str, str]]) -> str:
+    return json.dumps(
+        {
+            "tool_name": "MultiEdit",
+            "tool_input": {"file_path": str(file_path), "edits": all_edits},
+        }
+    )
+
+
+def _commit_and_stage_the_renamed_module(git_repository: Path, source_path: Path) -> None:
+    """Commit the base module, then stage an unrelated numeric change to it."""
+    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",
+    )
+
+
+def test_direct_hook_flags_refactor_in_second_multi_edit(git_repository: Path) -> None:
+    """A rename buried in the second edit of a MultiEdit is caught, not only the first.
+
+    The first edit is an ordinary numeric change; only the second edit renames
+    calculate_total to compute_total outside the currently staged diff.
+    """
+    source_path = git_repository / "module.py"
+    _commit_and_stage_the_renamed_module(git_repository, source_path)
+    payload_text = _multi_edit_payload(
+        source_path,
+        [
+            {"old_string": "return amount", "new_string": "return amount + 1"},
+            {
+                "old_string": "def calculate_total(amount: int) -> int:\n    return amount",
+                "new_string": "def compute_total(amount: int) -> int:\n    return amount",
+            },
+        ],
+    )
+
+    completed_hook = _run_hook(HOOK_SCRIPT_PATH, git_repository, payload_text)
+    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"]
+
+
+def test_direct_hook_stays_silent_for_ordinary_multi_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",
+    )
+    payload_text = _multi_edit_payload(
+        source_path,
+        [{"old_string": "return amount", "new_string": "return amount + 1"}],
+    )
+
+    completed_hook = _run_hook(HOOK_SCRIPT_PATH, git_repository, payload_text)
+
+    assert completed_hook.returncode == 0
+    assert completed_hook.stdout == ""