claude-dev-env 2.7.1 → 2.8.0

package/hooks/blocking/test_plain_language_blocker.py

@@ -2,8 +2,9 @@
 
 Covers the shared prose scanner (fenced code, inline code, blockquotes, URLs,
 file paths), the word-boundary guard, multi-word phrase matching, case
-insensitivity, the term -> replacement block message, and both registered
-PreToolUse surfaces (AskUserQuestion and Write|Edit on .md targets).
+insensitivity, the term -> replacement block message, both registered
+PreToolUse surfaces (AskUserQuestion and Write|Edit on .md targets), and the
+lean-question-block check that keeps chat detail out of an AskUserQuestion call.
 """
 
 import importlib.util
@@ -39,6 +40,9 @@ hook_module = _load_hook_module()
 find_banned_terms = hook_module.find_banned_terms
 strip_non_prose_regions = hook_module.strip_non_prose_regions
 build_block_reason = hook_module.build_block_reason
+find_question_block_violations = hook_module.find_question_block_violations
+build_lean_block_reason = hook_module.build_lean_block_reason
+evaluate = hook_module.evaluate
 
 from pre_tool_use_dispatcher import NativeHook, run_native_hook  # noqa: E402
 
@@ -296,3 +300,274 @@ def test_native_dispatch_path_logs_the_block(tmp_path: Path) -> None:
     logged_record = json.loads(all_records[0])
     assert logged_record["hook"] == "plain_language_blocker.py"
     assert logged_record["event"] == "PreToolUse"
+
+
+LEAN_QUESTION = "Which gate should run first?"
+LEAN_DESCRIPTION = "Runs on every write."
+QUESTION_AT_THE_WORD_CAP = (
+    "Should we keep the gate on the write path where it reads the whole file "
+    "each time, or move it to the commit path where it reads only the lines "
+    "that a change has already staged for the current review?"
+)
+QUESTION_OVER_THE_WORD_CAP = (
+    "Should we keep the gate on the write path where it reads the whole file "
+    "each time it runs, or move the gate to the commit path where it reads "
+    "only the staged lines and skips the files that no one on the team ever "
+    "touched?"
+)
+DESCRIPTION_AT_THE_WORD_CAP = (
+    "Runs the gate at commit time so it reads only the lines a change staged."
+)
+DESCRIPTION_OVER_THE_WORD_CAP = (
+    "Runs the gate at commit time so it reads only the lines the change "
+    "actually staged for review."
+)
+QUESTION_WITH_INLINE_CODE_AT_THE_WORD_CAP = (
+    "Should we keep the gate on the write path where it reads the whole file "
+    "each time, or move it to the commit path where it reads only what "
+    "`git diff --cached --name-only HEAD` lists for the current review before "
+    "the team sees it?"
+)
+QUESTION_WITH_INLINE_CODE_OVER_THE_WORD_CAP = (
+    "Should we keep the gate on the write path where it reads the whole file "
+    "each time, or move it to the commit path where it reads only what "
+    "`git diff --cached --name-only HEAD` lists for the current review before "
+    "the whole team sees it?"
+)
+DESCRIPTION_WITH_INLINE_CODE_AT_THE_WORD_CAP = (
+    "Runs the gate at commit time so it reads only what "
+    "`git diff --cached --name-only HEAD` lists for review."
+)
+DESCRIPTION_WITH_INLINE_CODE_OVER_THE_WORD_CAP = (
+    "Runs the gate at commit time so it reads only what "
+    "`git diff --cached --name-only HEAD` lists for the review."
+)
+
+
+def _ask_payload(question_text: str, all_descriptions: list[str]) -> dict[str, object]:
+    return {
+        "tool_name": "AskUserQuestion",
+        "tool_input": {
+            "questions": [
+                {
+                    "question": question_text,
+                    "header": "Gate",
+                    "options": [
+                        {"label": f"Gate {each_index}", "description": each_description}
+                        for each_index, each_description in enumerate(all_descriptions)
+                    ],
+                }
+            ]
+        },
+    }
+
+
+def test_question_carrying_a_list_marker_plan_is_denied() -> None:
+    plan_question = f"{LEAN_QUESTION}\n- Split the file\n- Wire the gate\n- Run the suite"
+
+    deny_reason = evaluate(_ask_payload(plan_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "a bullet or numbered list marker" in deny_reason
+
+
+def test_question_carrying_a_fenced_block_is_denied() -> None:
+    fenced_question = f"{LEAN_QUESTION}\n```\nrun_gate()\n```"
+
+    deny_reason = evaluate(_ask_payload(fenced_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "a fenced code block" in deny_reason
+
+
+def test_question_carrying_a_second_paragraph_is_denied() -> None:
+    two_paragraph_question = f"{LEAN_QUESTION}\n\nThe write gate reads every file."
+
+    deny_reason = evaluate(_ask_payload(two_paragraph_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "more than one paragraph" in deny_reason
+
+
+def test_question_carrying_a_one_line_fence_is_denied() -> None:
+    one_line_fence_question = f"{LEAN_QUESTION}\n```print(1)```"
+
+    deny_reason = evaluate(_ask_payload(one_line_fence_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "a fenced code block" in deny_reason
+
+
+def test_question_carrying_a_carriage_return_paragraph_break_is_denied() -> None:
+    crlf_question = f"{LEAN_QUESTION}\r\n\r\nThe write gate reads every file."
+
+    deny_reason = evaluate(_ask_payload(crlf_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "more than one paragraph" in deny_reason
+
+
+def test_question_carrying_a_heading_is_denied() -> None:
+    headed_question = f"{LEAN_QUESTION}\n## The write gate\nIt reads every file."
+
+    deny_reason = evaluate(_ask_payload(headed_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "a heading" in deny_reason
+
+
+def test_option_description_carrying_a_table_row_is_denied() -> None:
+    deny_reason = evaluate(_ask_payload(LEAN_QUESTION, ["| gate | 12 ms |"]))
+
+    assert deny_reason is not None
+    assert "a table row" in deny_reason
+
+
+def test_question_over_the_word_cap_is_denied() -> None:
+    deny_reason = evaluate(_ask_payload(QUESTION_OVER_THE_WORD_CAP, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "46 words, over the 40-word cap" in deny_reason
+
+
+def test_question_over_the_sentence_cap_is_denied() -> None:
+    three_sentence_question = (
+        "Which gate runs first? The write gate reads every file. "
+        "The commit gate reads staged lines only."
+    )
+
+    deny_reason = evaluate(_ask_payload(three_sentence_question, [LEAN_DESCRIPTION]))
+
+    assert deny_reason is not None
+    assert "3 sentences, over the 2-sentence cap" in deny_reason
+
+
+def test_option_description_over_the_word_cap_is_denied() -> None:
+    deny_reason = evaluate(_ask_payload(LEAN_QUESTION, [DESCRIPTION_OVER_THE_WORD_CAP]))
+
+    assert deny_reason is not None
+    assert "18 words, over the 15-word cap" in deny_reason
+
+
+def test_option_description_over_the_sentence_cap_is_denied() -> None:
+    deny_reason = evaluate(_ask_payload(LEAN_QUESTION, ["Runs on write. Reads every file."]))
+
+    assert deny_reason is not None
+    assert "2 sentences, over the 1-sentence cap" in deny_reason
+
+
+def test_lean_question_with_three_short_options_is_allowed() -> None:
+    all_descriptions = [
+        LEAN_DESCRIPTION,
+        "Runs at commit time.",
+        "Runs in both places.",
+    ]
+
+    assert evaluate(_ask_payload(LEAN_QUESTION, all_descriptions)) is None
+
+
+def test_two_sentence_question_at_the_sentence_cap_is_allowed() -> None:
+    two_sentence_question = f"{LEAN_QUESTION} Both gates read the same lines."
+
+    assert evaluate(_ask_payload(two_sentence_question, [LEAN_DESCRIPTION])) is None
+
+
+def test_question_at_the_word_cap_is_allowed() -> None:
+    assert evaluate(_ask_payload(QUESTION_AT_THE_WORD_CAP, [LEAN_DESCRIPTION])) is None
+
+
+def test_option_description_at_the_word_cap_is_allowed() -> None:
+    assert evaluate(_ask_payload(LEAN_QUESTION, [DESCRIPTION_AT_THE_WORD_CAP])) is None
+
+
+def test_question_with_an_inline_code_span_is_allowed() -> None:
+    question_text = QUESTION_WITH_INLINE_CODE_AT_THE_WORD_CAP
+
+    assert len(question_text.split()) > 40
+    assert evaluate(_ask_payload(question_text, [LEAN_DESCRIPTION])) is None
+
+
+def test_inline_code_span_counts_as_one_word() -> None:
+    deny_reason = evaluate(
+        _ask_payload(QUESTION_WITH_INLINE_CODE_OVER_THE_WORD_CAP, [LEAN_DESCRIPTION])
+    )
+
+    assert deny_reason is not None
+    assert "41 words, over the 40-word cap" in deny_reason
+
+
+def test_option_description_with_an_inline_code_span_is_allowed() -> None:
+    option_description = DESCRIPTION_WITH_INLINE_CODE_AT_THE_WORD_CAP
+
+    assert len(option_description.split()) > 15
+    assert evaluate(_ask_payload(LEAN_QUESTION, [option_description])) is None
+
+
+def test_inline_code_span_counts_as_one_word_in_an_option_description() -> None:
+    deny_reason = evaluate(
+        _ask_payload(LEAN_QUESTION, [DESCRIPTION_WITH_INLINE_CODE_OVER_THE_WORD_CAP])
+    )
+
+    assert deny_reason is not None
+    assert "16 words, over the 15-word cap" in deny_reason
+
+
+def test_markdown_write_keeps_its_bullets_and_tables(tmp_path: Path) -> None:
+    bulleted_prose = "- Split the file\n- Wire the gate\n\n| gate | 12 ms |\n"
+    target_path = str(tmp_path / "notes.md")
+    heavy_payload = {
+        "tool_name": "Write",
+        "tool_input": {
+            "file_path": target_path,
+            "content": f"{bulleted_prose}Then utilize the cache.",
+        },
+    }
+    clean_payload = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": target_path, "content": bulleted_prose},
+    }
+
+    assert evaluate(heavy_payload) is not None
+    assert evaluate(clean_payload) is None
+
+
+def test_find_question_block_violations_reports_one_line_per_repeated_fault() -> None:
+    tool_input = {
+        "questions": [
+            {
+                "question": LEAN_QUESTION,
+                "options": [
+                    {"label": "Write", "description": DESCRIPTION_OVER_THE_WORD_CAP},
+                    {"label": "Commit", "description": DESCRIPTION_OVER_THE_WORD_CAP},
+                ],
+            }
+        ]
+    }
+
+    all_violations = find_question_block_violations(tool_input)
+
+    assert all_violations == [
+        "an option description runs 18 words, over the 15-word cap"
+    ]
+
+
+def test_lean_block_reason_names_the_fault_and_the_fix() -> None:
+    reason = build_lean_block_reason(["the question carries a table row"])
+
+    assert "the question carries a table row" in reason
+    assert "in chat text" in reason
+
+
+def test_each_denial_carries_its_own_user_notice() -> None:
+    plan_question = f"{LEAN_QUESTION}\n- Split the file\n- Wire the gate"
+    lean_denial = _run_hook_with_payload(_ask_payload(plan_question, [LEAN_DESCRIPTION]))
+    heavy_denial = _run_hook_with_payload(
+        _ask_payload("Should we utilize the cache?", [LEAN_DESCRIPTION])
+    )
+
+    lean_notice = json.loads(lean_denial.stdout)["systemMessage"]
+    heavy_notice = json.loads(heavy_denial.stdout)["systemMessage"]
+
+    assert "question" in lean_notice.lower()
+    assert "word" in heavy_notice.lower()
+    assert lean_notice != heavy_notice

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -656,8 +656,11 @@ def test_dispatcher_edit_applies_both_groups() -> None:
     assert "blocking/stale_comment_reference_blocker.py" in all_edit_script_paths, (
         "stale_comment_reference_blocker belongs in the Edit applicable set"
     )
-    assert len(all_edit_entries) == 22, (
-        f"expected 22 Edit entries, got {len(all_edit_entries)}"
+    assert "advisory/refactor_guard.py" in all_edit_script_paths, (
+        "refactor_guard is Edit-scoped and hosted, so it belongs in the Edit applicable set"
+    )
+    assert len(all_edit_entries) == 24, (
+        f"expected 24 Edit entries, got {len(all_edit_entries)}"
     )
 
 
@@ -844,6 +847,35 @@ def test_runpy_hosted_hook_sees_its_own_argv_not_the_dispatchers(tmp_path: Path)
     )
 
 
+def test_folded_write_edit_hooks_have_no_standalone_hooks_json_entry() -> None:
+    """A hook the dispatcher hosts must not also run as its own process.
+
+    Each folded hook spawns an interpreter of its own when hooks.json still
+    registers it, so the fold only pays off once the standalone entry is gone.
+    """
+    hooks_json_text = (_HOOKS_ROOT / "hooks.json").read_text(encoding="utf-8")
+    hooks_configuration = json.loads(hooks_json_text)
+    all_pre_tool_use_commands = [
+        each_hook["command"]
+        for each_group in hooks_configuration["hooks"]["PreToolUse"]
+        for each_hook in each_group["hooks"]
+    ]
+    folded_script_relative_paths = (
+        "advisory/refactor_guard.py",
+        "advisory/migration_safety_advisor.py",
+    )
+    for each_script_path in folded_script_relative_paths:
+        matching_commands = [
+            each_command
+            for each_command in all_pre_tool_use_commands
+            if each_script_path in each_command
+        ]
+        assert not matching_commands, (
+            f"{each_script_path} is hosted by the dispatcher, so its standalone "
+            f"hooks.json entry must be gone. Found: {matching_commands!r}"
+        )
+
+
 def test_hosted_hook_set_covers_all_write_edit_blocking_hooks() -> None:
     """The hosted hook set covers all previously-registered Write/Edit blocking hooks.
 

package/hooks/git-hooks/CLAUDE.md

@@ -7,8 +7,8 @@ Native git hooks that run outside the Claude Code lifecycle — invoked directly
 | File | Git hook | What it does |
 |---|---|---|
 | `pre_commit.py` | `pre-commit` | Runs the CODE_RULES gate (`precommit_code_rules_gate.py`) over staged changes; exits 1 when any staged file has a blocking violation |
-| `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate over the commits about to be pushed |
-| `pre_push_base_reference.py` | — | Resolves the gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then names that remote's default branch from its symbolic ref or its candidate default branches |
+| `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate. An existing branch's gate base is the merge base with the remote default branch; the gate process still diffs that base against checkout HEAD, so the surface matches the pushed tip only when HEAD is that tip. |
+| `pre_push_base_reference.py` | — | Resolves a usable gate base for `pre_push.py`: reads the pushed remote name from git's arguments, then turns a symbolic default-branch head into a reference that git can resolve |
 | `post_commit.py` | `post-commit` | Runs after a commit lands; performs any post-commit bookkeeping |
 | `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
 | `test_config.py` | — | Test configuration helpers |

package/hooks/git-hooks/git_hooks_constants/__init__.py

@@ -47,7 +47,35 @@ NO_PARSEABLE_STDIN_LINES_MESSAGE: str = (
     "claude-dev-env pre-push: no parseable stdin lines; aborting"
 )
 NO_PARSEABLE_STDIN_LINES_SENTINEL: str = "__no_parseable_stdin_lines__"
+UNRESOLVABLE_MERGE_BASE_SENTINEL: str = "__unresolvable_merge_base__"
+UNRESOLVABLE_MERGE_BASE_MESSAGE: str = (
+    "claude-dev-env pre-push: git found no merge base between the pushed object "
+    "and the default branch, so the gate scope is unknown and "
+    "enforcement is skipped. That happens when the pushed branch and the "
+    "default branch hold unrelated histories, or when a default-branch ref "
+    "resolved and merge-base still could not name a shared commit "
+    "(for example a shallow clone missing the connecting history)."
+)
 LOCAL_BRANCH_REFERENCE_PREFIX: str = "refs/heads/"
+ORIGIN_HEAD_SYMBOLIC_REFERENCE: str = "refs/remotes/origin/HEAD"
+ORIGIN_REMOTE_TRACKING_REFERENCE_PREFIX: str = "refs/remotes/origin/"
+ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES: tuple[str, ...] = (
+    "refs/remotes/origin/main",
+    "refs/remotes/origin/master",
+)
+ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX: tuple[str, ...] = (
+    "git",
+    "symbolic-ref",
+    "--quiet",
+)
+ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX: tuple[str, ...] = (
+    "git",
+    "rev-parse",
+    "--verify",
+    "--quiet",
+)
+ALL_GIT_MERGE_BASE_COMMAND_PREFIX: tuple[str, ...] = ("git", "merge-base")
+GIT_REFERENCE_QUERY_TIMEOUT_SECONDS: int = 15
 CODE_REVIEW_PUSH_GATE_PATH_OVERRIDE_ENV_VAR: str = "CODE_REVIEW_PUSH_GATE_PATH"
 CODE_REVIEW_PUSH_GATE_MODULE_NAME: str = "code_review_push_gate"
 CODE_REVIEW_PUSH_GATE_SCRIPT_FILENAME: str = "code_review_push_gate.py"