claude-dev-env 7.4.0 → 7.5.0

package/hooks/blocking/test_env_var_table_code_drift_blocker.py

@@ -125,9 +125,10 @@ def test_production_entrypoint_denies_drifted_table(tmp_path: Path) -> None:
     hook_specific_output = parsed_payload["hookSpecificOutput"]
     assert completed.returncode == 0, completed.stderr
     assert hook_specific_output["permissionDecision"] == "deny"
-    assert "GOOGLE_APPLICATION_CREDENTIALS -> auth/google_auth.py" in hook_specific_output[
-        "permissionDecisionReason"
-    ]
+    assert (
+        "GOOGLE_APPLICATION_CREDENTIALS -> auth/google_auth.py"
+        in hook_specific_output["permissionDecisionReason"]
+    )
     assert_hook_deny_log_contains(tmp_path, "env_var_table_code_drift_blocker.py")
 
 
@@ -159,3 +160,80 @@ def test_ignores_row_whose_second_cell_is_not_a_code_file(tmp_path: Path) -> Non
         "| `SOME_FLAG` | `enables the thing` | off |\n"
     )
     assert find_drift_rows(content, doc_path.parent) == []
+
+
+def test_constant_tables_do_not_claim_environment_consumers(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Symbol | Imported by |\n"
+        "| --- | --- |\n"
+        "| `PROCESSING_VISIBLE` | `workflow.py` |\n\n"
+        "| Component | Location | Purpose |\n"
+        "| --- | --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` | Selector |\n\n"
+        "| Constant | Value | Source |\n"
+        "| --- | --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | 5 | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == []
+
+
+def test_environment_table_after_constants_still_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n\n"
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_environment_section_supports_name_header(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_headerless_edit_fragment_still_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_descriptive_environment_header_reports_drift(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "| Environment Variable Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]
+
+
+def test_explicit_source_header_overrides_environment_section(tmp_path: Path) -> None:
+    _anchor_repo_root(tmp_path)
+    _write(tmp_path / "workflow.py", "def run():\n    return\n")
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n\n"
+        "The source also defines a delay constant.\n\n"
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n"
+    )
+    assert find_drift_rows(content, tmp_path) == ["UPLOAD_TOKEN -> workflow.py"]

package/hooks/blocking/test_env_var_table_rows.py

@@ -0,0 +1,100 @@
+"""Tests for environment-variable table row recognition.
+
+Each test drives ``iter_env_var_table_rows`` against markdown text and asserts
+the exact rows it yields. The behavior under test is table context: which
+markdown tables read as environment-variable summaries, and which read as
+source, constant, or component tables that name no environment consumer.
+"""
+
+from __future__ import annotations
+
+from env_var_table_rows import iter_env_var_table_rows
+
+
+def test_environment_variable_header_yields_data_rows() -> None:
+    content = (
+        "| Environment variable | Consumer |\n| --- | --- |\n| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Environment variable | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_constant_table_yields_nothing() -> None:
+    content = (
+        "| Constant | Value | Source |\n"
+        "| --- | --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | 5 | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_component_table_yields_nothing() -> None:
+    content = (
+        "| Component | Location | Purpose |\n"
+        "| --- | --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` | Selector |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_generic_name_header_under_environment_heading_yields_rows() -> None:
+    content = (
+        "## Environment variables\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Name | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_generic_name_header_without_environment_heading_yields_nothing() -> None:
+    content = (
+        "## Selectors\n\n"
+        "| Name | Consumer |\n"
+        "| --- | --- |\n"
+        "| `ACCOUNT_LINK_PRIMARY` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_headerless_fragment_naming_a_variable_yields_the_row() -> None:
+    content = "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    assert list(iter_env_var_table_rows(content)) == ["| `UPLOAD_TOKEN` | `workflow.py` |"]
+
+
+def test_rows_inside_a_code_fence_yield_nothing() -> None:
+    content = (
+        "```markdown\n"
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n"
+        "```\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == []
+
+
+def test_constant_table_after_an_environment_table_yields_nothing_extra() -> None:
+    content = (
+        "| Environment variable | Consumer |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_TOKEN` | `workflow.py` |\n\n"
+        "| Constant | Source |\n"
+        "| --- | --- |\n"
+        "| `UPLOAD_DELAY_SECONDS` | `workflow.py` |\n"
+    )
+    assert list(iter_env_var_table_rows(content)) == [
+        "| Environment variable | Consumer |",
+        "| `UPLOAD_TOKEN` | `workflow.py` |",
+    ]
+
+
+def test_separator_row_is_never_yielded() -> None:
+    content = (
+        "| Environment variable | Consumer |\n| :--- | ---: |\n| `UPLOAD_TOKEN` | `workflow.py` |\n"
+    )
+    assert "| :--- | ---: |" not in list(iter_env_var_table_rows(content))

package/hooks/blocking/test_msys_rev_path_rewriter.py

@@ -0,0 +1,141 @@
+"""Tests for msys_rev_path_rewriter, the MSYS <rev>:<path> exclusion rewriter."""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from unittest.mock import patch
+
+import msys_rev_path_rewriter as rewriter
+
+SETTINGS_SHOW_COMMAND = "git show origin/main:.claude/settings.json"
+SETTINGS_SHOW_REWRITTEN = (
+    "export MSYS2_ARG_CONV_EXCL='origin/main:'; git show origin/main:.claude/settings.json"
+)
+
+
+def _stdout_from_main(payload: dict[str, object]) -> str:
+    """Return what main() wrote to stdout for one hook payload."""
+    captured_stdout = StringIO()
+    with patch("sys.stdin", StringIO(json.dumps(payload))), patch("sys.stdout", captured_stdout):
+        try:
+            rewriter.main()
+        except SystemExit:
+            pass
+    return captured_stdout.getvalue()
+
+
+def test_settings_path_after_slashed_revision_yields_one_prefix() -> None:
+    assert rewriter.all_exclusion_prefixes(SETTINGS_SHOW_COMMAND) == ("origin/main:",)
+
+
+def test_settings_path_command_gains_the_surgical_export_prefix() -> None:
+    assert rewriter.command_with_exclusion_export(SETTINGS_SHOW_COMMAND) == SETTINGS_SHOW_REWRITTEN
+
+
+def test_unslashed_revision_beside_a_slashed_one_stays_out_of_the_prefixes() -> None:
+    assert rewriter.all_exclusion_prefixes(
+        "git diff origin/main:.gitignore HEAD:.gitignore"
+    ) == ("origin/main:",)
+
+
+def test_two_slashed_revisions_join_with_a_semicolon_in_first_appearance_order() -> None:
+    assert rewriter.command_with_exclusion_export(
+        "git diff origin/main:.gitignore origin/develop:.gitignore"
+    ) == (
+        "export MSYS2_ARG_CONV_EXCL='origin/main:;origin/develop:'; "
+        "git diff origin/main:.gitignore origin/develop:.gitignore"
+    )
+
+
+def test_one_slashed_revision_used_twice_yields_one_prefix() -> None:
+    assert rewriter.all_exclusion_prefixes(
+        "git diff origin/main:.gitignore origin/main:.gitattributes"
+    ) == ("origin/main:",)
+
+
+def test_dot_file_after_the_colon_is_collected() -> None:
+    assert rewriter.all_exclusion_prefixes("git show origin/main:.gitignore") == ("origin/main:",)
+
+
+def test_plain_directory_path_after_the_colon_is_left_alone() -> None:
+    command = "git show origin/main:packages/app.py"
+    assert rewriter.all_exclusion_prefixes(command) == ()
+    assert rewriter.command_with_exclusion_export(command) == command
+
+
+def test_revision_without_a_slash_is_left_alone() -> None:
+    command = "git show HEAD:.claude/settings.json"
+    assert rewriter.all_exclusion_prefixes(command) == ()
+    assert rewriter.command_with_exclusion_export(command) == command
+
+
+def test_dot_slash_path_after_the_colon_is_left_alone() -> None:
+    assert rewriter.all_exclusion_prefixes("git show origin/main:./settings.json") == ()
+
+
+def test_parent_directory_path_after_the_colon_is_left_alone() -> None:
+    assert rewriter.all_exclusion_prefixes("git show origin/main:../settings.json") == ()
+
+
+def test_command_already_naming_the_exclusion_variable_is_left_alone() -> None:
+    command = "MSYS2_ARG_CONV_EXCL='*' git show origin/main:.gitignore"
+    assert rewriter.command_with_exclusion_export(command) == command
+
+
+def test_command_already_naming_the_path_conversion_variable_is_left_alone() -> None:
+    command = "export MSYS_NO_PATHCONV=1; git show origin/main:.gitignore"
+    assert rewriter.command_with_exclusion_export(command) == command
+
+
+def test_colon_token_in_a_non_git_segment_is_left_alone() -> None:
+    assert rewriter.all_exclusion_prefixes("echo origin/main:.gitignore") == ()
+
+
+def test_quoted_message_token_carrying_a_slash_and_a_dot_is_left_alone() -> None:
+    command = "git commit -m \"don't touch a/b:.x\""
+    assert rewriter.all_exclusion_prefixes(command) == ()
+    assert rewriter.command_with_exclusion_export(command) == command
+
+
+def test_url_token_in_a_curl_command_is_left_alone() -> None:
+    assert rewriter.all_exclusion_prefixes("curl https://example.com/x") == ()
+
+
+def test_git_segment_after_a_non_git_segment_still_contributes() -> None:
+    assert rewriter.all_exclusion_prefixes(
+        "echo start && git show origin/main:.gitignore"
+    ) == ("origin/main:",)
+
+
+def test_main_emits_an_allow_carrying_the_rewritten_command() -> None:
+    emitted_text = _stdout_from_main(
+        {
+            "tool_name": "Bash",
+            "tool_input": {"command": SETTINGS_SHOW_COMMAND, "description": "read settings"},
+        }
+    )
+    assert json.loads(emitted_text) == {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+            "updatedInput": {
+                "command": SETTINGS_SHOW_REWRITTEN,
+                "description": "read settings",
+            },
+        }
+    }
+
+
+def test_main_emits_nothing_for_a_non_bash_tool() -> None:
+    emitted_text = _stdout_from_main(
+        {"tool_name": "PowerShell", "tool_input": {"command": SETTINGS_SHOW_COMMAND}}
+    )
+    assert emitted_text == ""
+
+
+def test_main_emits_nothing_for_a_command_with_no_collected_prefix() -> None:
+    emitted_text = _stdout_from_main(
+        {"tool_name": "Bash", "tool_input": {"command": "git show HEAD:.gitignore"}}
+    )
+    assert emitted_text == ""

package/hooks/blocking/test_pii_scanner.py

@@ -55,17 +55,13 @@ def test_allows_hygiene_placeholder_username_example() -> None:
 
 
 def test_flags_unix_home_path() -> None:
-    all_unix_hits = scan_text_for_pii(
-        "config lives in /Users/fixture_real_user/.config"
-    )
+    all_unix_hits = scan_text_for_pii("config lives in /Users/fixture_real_user/.config")
     assert any(each.category == "home-path" for each in all_unix_hits)
 
 
 def test_flags_raw_escaped_windows_home_path() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\\Users\\concrete-user\\file")
-    assert [each.matched_text for each in all_home_hits] == [
-        r"C:\\Users\\concrete-user"
-    ]
+    assert [each.matched_text for each in all_home_hits] == [r"C:\\Users\\concrete-user"]
 
 
 def test_flags_unc_windows_home_path_at_each_share_depth() -> None:
@@ -82,9 +78,7 @@ def test_flags_unc_windows_home_path_at_each_share_depth() -> None:
 
 def test_flags_forward_slash_unc_home_paths() -> None:
     all_home_hits = scan_text_for_pii(
-        "path is //server/Users/concrete-user/file"
-        "\n"
-        "path is //server/share/Users/other-user/file"
+        "path is //server/Users/concrete-user/file\npath is //server/share/Users/other-user/file"
     )
     assert [each.matched_text for each in all_home_hits] == [
         "//server/Users/concrete-user",
@@ -112,9 +106,7 @@ def test_flags_absolute_and_file_uri_home_paths() -> None:
     all_home_hits += scan_text_for_pii("path is file:///home/concrete-user/file")
     all_home_hits += scan_text_for_pii("path is file://server/home/concrete-user/file")
     all_home_hits += scan_text_for_pii("path is FILE://server/home/other-user/file")
-    all_home_hits += scan_text_for_pii(
-        "path is FILE://server/share/home/third-user/file"
-    )
+    all_home_hits += scan_text_for_pii("path is FILE://server/share/home/third-user/file")
     assert [each.matched_text for each in all_home_hits] == [
         "/home/concrete-user",
         "file:///home/concrete-user",
@@ -191,9 +183,7 @@ def test_flags_github_token_aws_key_and_pem_header() -> None:
 def test_secret_and_email_previews_are_redacted() -> None:
     all_secret_hits = scan_text_for_pii(f"export TOKEN={SYNTHETIC_GITHUB_TOKEN}")
     all_email_hits = scan_text_for_pii(f"contact {SYNTHETIC_REAL_EMAIL}")
-    secret_finding = next(
-        each for each in all_secret_hits if each.category == "secret"
-    )
+    secret_finding = next(each for each in all_secret_hits if each.category == "secret")
     email_finding = next(each for each in all_email_hits if each.category == "email")
     assert secret_finding.matched_text == SYNTHETIC_GITHUB_TOKEN
     assert SYNTHETIC_GITHUB_TOKEN not in secret_finding.preview
@@ -217,9 +207,7 @@ def test_flags_genuine_human_home_username() -> None:
 
 def test_short_nonsafe_email_preview_is_fully_redacted() -> None:
     all_email_hits = scan_text_for_pii("reach owner@acme.io")
-    email_finding = next(
-        each for each in all_email_hits if each.category == "email"
-    )
+    email_finding = next(each for each in all_email_hits if each.category == "email")
     assert email_finding.matched_text == "owner@acme.io"
     assert email_finding.preview == "[redacted]"
     assert "owner" not in email_finding.preview
@@ -227,9 +215,7 @@ def test_short_nonsafe_email_preview_is_fully_redacted() -> None:
 
 def test_home_path_preview_redacts_only_the_username() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\Users\johnsmith\secret.txt")
-    home_finding = next(
-        each for each in all_home_hits if each.category == "home-path"
-    )
+    home_finding = next(each for each in all_home_hits if each.category == "home-path")
     assert "johnsmith" not in home_finding.preview
     assert "[redacted]" in home_finding.preview
     assert "Users" in home_finding.preview
@@ -237,9 +223,7 @@ def test_home_path_preview_redacts_only_the_username() -> None:
 
 def test_home_path_preview_redacts_home_segment_when_name_repeats_earlier() -> None:
     all_home_hits = scan_text_for_pii(r"path is C:\Users\Users\secret.txt")
-    home_finding = next(
-        each for each in all_home_hits if each.category == "home-path"
-    )
+    home_finding = next(each for each in all_home_hits if each.category == "home-path")
     assert home_finding.preview == r"C:\Users\[redacted]"
 
 
@@ -269,3 +253,29 @@ def test_path_exemptions_for_tests_license_and_self_modules() -> None:
 def test_empty_path_still_scans_payload_text() -> None:
     all_hits = scan_text_for_pii(f"contact {SYNTHETIC_REAL_EMAIL}")
     assert any(each.category == "email" for each in all_hits)
+
+
+def test_home_match_stops_at_source_string_boundary() -> None:
+    findings = scan_text_for_pii('path = "C:/Users/concrete-user"\nnext_path = "C:/data"')
+    assert [(item.category, item.matched_text) for item in findings] == [
+        ("home-path", "C:/Users/concrete-user")
+    ]
+
+
+def test_allows_interpolated_home_username() -> None:
+    assert scan_text_for_pii('path = f"C:/Users/{username}/Documents"') == []
+    assert scan_text_for_pii('path = f"C:/Users/{username}"\nnext_path = "C:/data"') == []
+
+
+def test_template_username_does_not_exempt_literal_username() -> None:
+    findings = scan_text_for_pii('path = "C:/Users/concrete-user{suffix}/Documents"')
+    assert [item.category for item in findings] == ["home-path"]
+
+
+def test_preserves_apostrophes_and_parentheses_in_usernames() -> None:
+    findings = scan_text_for_pii("C:/Users/O'Neil/Documents\nC:/Users/Jane (Work)/Documents")
+    assert [item.matched_text for item in findings] == ["C:/Users/O'Neil", "C:/Users/Jane (Work)"]
+
+
+def test_escaped_placeholder_username_uses_complete_separator() -> None:
+    assert scan_text_for_pii(r"C:\\Users\\example\\Documents") == []

package/hooks/hooks.json

@@ -12,6 +12,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/bash_pre_tool_use_dispatcher.py",
+            "timeout": 60
+          }
+        ]
+      },
       {
         "matcher": "EnterWorktree",
         "hooks": [

package/hooks/hooks_constants/bash_post_call_dispatcher_constants.py

@@ -5,6 +5,10 @@ finishes. Reuses ``BashHostedHookEntry`` and the Bash-only tool-name set from
 ``bash_pre_tool_use_dispatcher_constants`` -- the entry shape and the tool-name
 membership question are identical on the PostToolUse side, so this module adds
 no second copy of either.
+
+Also the one home for the harness PostToolUse output contract every hook on
+this roster shares: the exit-code prefix a failed call's response text opens
+with, and the three payload keys that carry a context note back to the agent.
 """
 
 from __future__ import annotations
@@ -17,8 +21,10 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
 
 __all__ = [
     "ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES",
+    "EXIT_CODE_ERROR_PREFIX",
     "POST_TOOL_USE_HOOK_EVENT_NAME",
     "HOOK_SPECIFIC_OUTPUT_KEY",
+    "HOOK_EVENT_NAME_KEY",
     "ADDITIONAL_CONTEXT_KEY",
     "ADDITIONAL_CONTEXT_JOIN_SEPARATOR",
 ]
@@ -26,9 +32,12 @@ __all__ = [
 ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry("observability/test_failure_recorder.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("advisory/pr_done_reminder.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES),
+    BashHostedHookEntry("advisory/msys_path_conversion_advisor.py", ALL_BASH_ONLY_TOOL_NAMES),
 )
 
+EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
 POST_TOOL_USE_HOOK_EVENT_NAME: str = "PostToolUse"
 HOOK_SPECIFIC_OUTPUT_KEY: str = "hookSpecificOutput"
+HOOK_EVENT_NAME_KEY: str = "hookEventName"
 ADDITIONAL_CONTEXT_KEY: str = "additionalContext"
 ADDITIONAL_CONTEXT_JOIN_SEPARATOR: str = "\n\n"

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -54,4 +54,9 @@ class BashHostedHookEntry:
     applicable_tool_names: frozenset[str]
 
 
-ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = ()
+ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
+    BashHostedHookEntry(
+        script_relative_path="blocking/msys_rev_path_rewriter.py",
+        applicable_tool_names=ALL_BASH_ONLY_TOOL_NAMES,
+    ),
+)

package/hooks/hooks_constants/env_var_table_code_drift_constants.py

@@ -16,6 +16,9 @@ __all__ = [
     "SEPARATOR_CELL_PATTERN",
     "BACKTICK_TOKEN_PATTERN",
     "ENV_VAR_NAME_PATTERN",
+    "ENV_VAR_HEADER_PATTERN",
+    "ALL_GENERIC_ENV_VAR_HEADERS",
+    "ENV_VAR_HEADING_PATTERN",
     "ALL_CODE_FILE_EXTENSIONS",
     "ALL_NOISE_DIRECTORY_NAMES",
     "GIT_DIRECTORY_NAME",
@@ -34,10 +37,13 @@ CODE_FENCE_PATTERN = re.compile(r"^\s*(```|~~~)")
 SEPARATOR_CELL_PATTERN = re.compile(r"^[:\-\s]+$")
 BACKTICK_TOKEN_PATTERN = re.compile(r"`([^`]+)`")
 ENV_VAR_NAME_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]{1,}$")
-
-ALL_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset(
-    {".py", ".mjs", ".js", ".ts", ".ps1", ".sh"}
+ENV_VAR_HEADER_PATTERN = re.compile(
+    r"^(?:(?:environment|env)[ -]+)?(?:variables?|vars?)(?:[ -]+(?:name|key))?$", re.I
 )
+ALL_GENERIC_ENV_VAR_HEADERS = frozenset({"name", "key"})
+ENV_VAR_HEADING_PATTERN = re.compile(r"\b(?:environment|env)[ -]+(?:variables?|vars?)\b", re.I)
+
+ALL_CODE_FILE_EXTENSIONS: frozenset[str] = frozenset({".py", ".mjs", ".js", ".ts", ".ps1", ".sh"})
 ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
     {".git", "__pycache__", "node_modules", ".pytest_cache", ".mypy_cache", ".ruff_cache"}
 )
@@ -61,4 +67,6 @@ DRIFT_ADDITIONAL_CONTEXT = (
     "its source never references the variable name, the row is stale. Drop the "
     "row, or point it at the variable the file actually reads."
 )
-DRIFT_SYSTEM_MESSAGE = "Blocked: env-var summary table attributes a variable to a code file that does not read it."
+DRIFT_SYSTEM_MESSAGE = (
+    "Blocked: env-var summary table attributes a variable to a code file that does not read it."
+)

package/hooks/hooks_constants/hardcoded_user_path_constants.py

@@ -4,15 +4,17 @@ import re
 
 HARDCODED_USER_PATH_PATTERN: re.Pattern[str] = re.compile(
     r"(?:"
-    r"[A-Za-z]:[\\/]+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
-    r"|\\{2,}(?:[^\\/\r\n]+[\\/]+)+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))[^\\/]+(?=[\\/]|$)"
-    r"|(?<!:)//(?:[^\\/\r\n]+/)+(?i:users)/(?!(?i:Public|Shared|All Users)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file):///Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:Users)/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?i:file):///home/[^/]+(?=/|$)"
-    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:home)/[^/]+(?=/|$)"
-    r"|(?<![A-Za-z0-9._:/\-\]])/Users/(?!(?i:Shared|Public)(?:/|$))[^/]+(?=/|$)"
-    r"|(?<![A-Za-z0-9._:/\-\]])/home/[^/]+(?=/|$))"
+    r"[A-Za-z]:[\\/]+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))(?:[^\\/\r\n\"`]+(?=[\\/])|[^\\/\r\n\"'`()]+(?=[\\/\r\n\"'`()]|$))"
+    r"|\\{2,}(?:[^\\/\r\n]+[\\/]+)+(?i:users)[\\/]+(?!(?i:Public|Shared|All Users)(?:[\\/]|$))(?:[^\\/\r\n\"`]+(?=[\\/])|[^\\/\r\n\"'`()]+(?=[\\/\r\n\"'`()]|$))"
+    r"|(?<!:)//(?:[^\\/\r\n]+/)+(?i:users)/(?!(?i:Public|Shared|All Users)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file):///Users/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:Users)/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file):///home/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?i:file)://(?:[^/\r\n]+/)+(?i:home)/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?<![A-Za-z0-9._:/\-\]])/Users/(?!(?i:Shared|Public)(?:/|$))(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$))"
+    r"|(?<![A-Za-z0-9._:/\-\]])/home/(?:[^/\r\n\"`]+(?=/)|[^/\r\n\"'`()]+(?=[/\r\n\"'`()]|$)))"
 )
 MAX_HARDCODED_USER_PATH_ISSUES: int = 25
-HARDCODED_USER_PATH_GUIDANCE: str = "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"
+HARDCODED_USER_PATH_GUIDANCE: str = (
+    "use pathlib.Path.home() or os.path.expanduser('~') instead of a hardcoded user directory"
+)

package/hooks/hooks_constants/msys_path_conversion_advisor_constants.py

@@ -0,0 +1,48 @@
+"""Constants for the MSYS path-conversion context advisory.
+
+The advisory is a PostToolUse observer on Bash. It never blocks. When a git
+call fails because Git Bash rewrote a ``<rev>:<path>`` argument before git saw
+it, the advisory adds one loud note naming the two exports that turn the
+rewriting off.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_MANGLED_ARGUMENT_MARKERS",
+    "MANGLED_ARGUMENT_CLOSING_QUOTE",
+    "ALL_MSYS_MANGLING_CHARACTERS",
+    "ALL_MSYS_PATH_CONVERSION_VARIABLE_NAMES",
+    "ADVISORY_HEADER",
+    "MANGLED_ARGUMENT_LINE_TEMPLATE",
+    "MANGLING_EXPLANATION_LINE",
+    "FIX_LINE",
+    "SAME_COMMAND_LINE",
+    "ADVISORY_LINE_SEPARATOR",
+]
+
+AMBIGUOUS_ARGUMENT_MARKER: str = "fatal: ambiguous argument '"
+INVALID_OBJECT_NAME_MARKER: str = "fatal: invalid object name '"
+ALL_MANGLED_ARGUMENT_MARKERS: tuple[str, ...] = (
+    AMBIGUOUS_ARGUMENT_MARKER,
+    INVALID_OBJECT_NAME_MARKER,
+)
+MANGLED_ARGUMENT_CLOSING_QUOTE: str = "'"
+ALL_MSYS_MANGLING_CHARACTERS: frozenset[str] = frozenset({"\\", ";"})
+MSYS_PATH_CONVERSION_VARIABLE_NAME: str = "MSYS_NO_PATHCONV"
+MSYS_ARGUMENT_CONVERSION_EXCLUSION_VARIABLE_NAME: str = "MSYS2_ARG_CONV_EXCL"
+ALL_MSYS_PATH_CONVERSION_VARIABLE_NAMES: tuple[str, ...] = (
+    MSYS_PATH_CONVERSION_VARIABLE_NAME,
+    MSYS_ARGUMENT_CONVERSION_EXCLUSION_VARIABLE_NAME,
+)
+MSYS_EXPORT_FIX_LINE: str = "export MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*'"
+
+ADVISORY_HEADER: str = "=== MSYS PATH CONVERSION (context reminder, never a block) ==="
+MANGLED_ARGUMENT_LINE_TEMPLATE: str = "Git saw:     {argument}"
+MANGLING_EXPLANATION_LINE: str = (
+    "Git Bash rewrote a <rev>:<path> argument before git saw it, turning the "
+    "colon into a semicolon and the slashes into backslashes."
+)
+FIX_LINE: str = "Fix:         " + MSYS_EXPORT_FIX_LINE
+SAME_COMMAND_LINE: str = "Put that export and the git command in the same command."
+ADVISORY_LINE_SEPARATOR: str = "\n"

package/hooks/hooks_constants/msys_rev_path_rewriter_constants.py

@@ -0,0 +1,37 @@
+"""Constants for the MSYS ``<rev>:<path>`` argument-exclusion rewriter.
+
+Git Bash converts a git argument such as ``origin/main:.claude/settings.json``
+before git sees it. ``MSYS2_ARG_CONV_EXCL`` takes a semicolon-separated list of
+argument prefixes to leave alone, so naming one ``<rev>:`` prefix per detected
+token keeps every other argument in the command converting as before.
+"""
+
+from __future__ import annotations
+
+from hooks_constants.msys_path_conversion_advisor_constants import (
+    MSYS_ARGUMENT_CONVERSION_EXCLUSION_VARIABLE_NAME,
+)
+
+__all__ = [
+    "GIT_PROGRAM_NAME",
+    "REVISION_PATH_SEPARATOR",
+    "REVISION_PATH_SPLIT_COUNT",
+    "REVISION_SLASH_CHARACTER",
+    "ALL_CONVERTED_PATH_START_CHARACTERS",
+    "ALL_UNCONVERTED_PATH_START_PREFIXES",
+    "ALL_REVISION_FORBIDDEN_CHARACTERS",
+    "EXCLUSION_PREFIX_JOIN_SEPARATOR",
+    "EXCLUSION_EXPORT_TEMPLATE",
+]
+
+GIT_PROGRAM_NAME: str = "git"
+REVISION_PATH_SEPARATOR: str = ":"
+REVISION_PATH_SPLIT_COUNT: int = 1
+REVISION_SLASH_CHARACTER: str = "/"
+ALL_CONVERTED_PATH_START_CHARACTERS: tuple[str, ...] = ("/", ".")
+ALL_UNCONVERTED_PATH_START_PREFIXES: tuple[str, ...] = ("./", "../")
+ALL_REVISION_FORBIDDEN_CHARACTERS: tuple[str, ...] = ("'", '"')
+EXCLUSION_PREFIX_JOIN_SEPARATOR: str = ";"
+EXCLUSION_EXPORT_TEMPLATE: str = (
+    "export " + MSYS_ARGUMENT_CONVERSION_EXCLUSION_VARIABLE_NAME + "='{all_prefixes}'; "
+)