claude-dev-env 1.21.1 → 1.22.0

package/hooks/blocking/_gh_body_arg_utils.py

@@ -0,0 +1,48 @@
+"""Shared gh body-arg parsing utilities for blocking hooks."""
+
+body_file_flag: str = "--body-file"
+body_file_flag_prefix: str = "--body-file="
+
+all_body_flags: frozenset[str] = frozenset({"--body", "-b"})
+all_body_flag_prefixes: tuple[str, ...] = ("--body=", "-b=")
+all_value_flags: frozenset[str] = frozenset(
+    {
+        "--title",
+        "-t",
+        "--reviewer",
+        "-r",
+        "--assignee",
+        "-a",
+        "--label",
+        "-l",
+        "--milestone",
+        "-m",
+        "--project",
+        "-p",
+        "--base",
+        "-B",
+        "--head",
+        "-H",
+        "--repo",
+        "-R",
+        body_file_flag,
+    }
+)
+
+
+def get_logical_first_line(command: str) -> str:
+    logical = ""
+    for each_line in command.splitlines():
+        stripped_line = each_line.rstrip()
+        is_backslash_continuation = (
+            stripped_line.endswith("\\") and stripped_line.count("\\") % 2 == 1
+        )
+        is_powershell_backtick_continuation = (
+            stripped_line.endswith("`") and stripped_line.count("`") % 2 == 1
+        )
+        if is_backslash_continuation or is_powershell_backtick_continuation:
+            logical += stripped_line[:-1].rstrip() + " "
+        else:
+            logical += each_line
+            break
+    return logical.strip()

package/hooks/blocking/gh-body-arg-blocker.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block gh commands that use --body <string> instead of --body-file.
+
+Root cause: in shell-invoked gh command contexts, passing markdown body text via
+--body "..." can cause backticks to be stored as literal backslash-backtick sequences
+on GitHub instead of rendering as inline code or code fences. Quoting and escaping
+rules vary by execution environment (Bash, PowerShell, CMD) but the failure mode is
+the same. The fix is always to write the body to a temp file and pass --body-file.
+
+Affected subcommands: gh issue create/edit/comment, gh pr create/edit/comment/review.
+
+Detection strategy: join bash \\ and PowerShell ` line continuations into a single
+logical line, then use shlex.split(..., posix=False) on that line so '--body'
+appearing inside a quoted flag value or in heredoc body content on non-continuation
+lines does not trigger a false positive. Both '--body value' and '--body=value' forms are blocked,
+as are their short '-b' equivalents. '--body-file' and '--body-file=...' are allowed.
+Falls back to a conservative approve if the logical line is unparseable.
+"""
+
+import json
+import re
+import shlex
+import sys
+
+from _gh_body_arg_utils import (
+    all_body_flags,
+    all_body_flag_prefixes,
+    all_value_flags,
+    get_logical_first_line,
+)
+
+_GH_BODY_SUBCOMMANDS = re.compile(
+    r"\bgh\s+(?:"
+    r"issue\s+(?:create|edit|comment)|"
+    r"pr\s+(?:create|edit|comment|review)"
+    r")\b",
+    re.IGNORECASE,
+)
+
+_BASH_TOOL_NAME = "Bash"
+
+_CORRECTIVE_MESSAGE = (
+    "BLOCKED [gh-body-file]: gh --body <string> escapes backticks as \\` on GitHub, "
+    "corrupting inline code and code fences in issues, PRs, comments, and reviews. "
+    "Write the body to a temp file and use --body-file instead.\n\n"
+    "Safe Python pattern:\n"
+    "  import tempfile\n"
+    "  with tempfile.NamedTemporaryFile(mode='w', suffix='.md', delete=False) as f:\n"
+    "      f.write(body_text)\n"
+    "      body_path = f.name\n"
+    "  # then: gh ... --body-file body_path\n\n"
+    "Safe PowerShell pattern:\n"
+    "  $bodyPath = [System.IO.Path]::ChangeExtension((New-TemporaryFile).FullName, '.md')\n"
+    "  @'\n"
+    "  <your markdown body>\n"
+    "  '@ | Set-Content -Path $bodyPath -Encoding utf8\n"
+    "  gh ... --body-file $bodyPath\n\n"
+    "See ~/.claude/rules/gh-body-file.md for full guidance."
+)
+
+
+def _uses_body_string_arg(command: str) -> bool:
+    """Return True if command calls an affected gh subcommand with --body <string>.
+
+    Joins bash \\ and PowerShell ` line continuations before scanning so that
+    '--body' on a continuation line is not missed. Uses shlex.split(posix=False)
+    for Windows-friendly tokenization: backslashes in unquoted paths are preserved
+    and quoted values retain their surrounding quotes as part of the token, so
+    '--body' embedded in a quoted value cannot be mistaken for a standalone flag.
+    Detects both '--body value'/'--body=value' forms and their short '-b'
+    equivalents. Falls back to a conservative approve if the line is unparseable.
+    """
+    logical_line = get_logical_first_line(command)
+    if not _GH_BODY_SUBCOMMANDS.search(logical_line):
+        return False
+    try:
+        tokens = shlex.split(logical_line, posix=False)
+    except ValueError:
+        return False
+    should_skip_next_token = False
+    for each_token in tokens:
+        if should_skip_next_token:
+            should_skip_next_token = False
+            continue
+        if each_token in all_body_flags or any(
+            each_token.startswith(each_prefix) for each_prefix in all_body_flag_prefixes
+        ):
+            return True
+        if each_token in all_value_flags:
+            should_skip_next_token = True
+    return False
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name != _BASH_TOOL_NAME:
+        sys.exit(0)
+
+    command = hook_input.get("tool_input", {}).get("command", "")
+    if not command:
+        sys.exit(0)
+
+    if not _uses_body_string_arg(command):
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _CORRECTIVE_MESSAGE,
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_gh_body_arg_blocker.py

@@ -0,0 +1,148 @@
+"""Unit tests for gh-body-arg-blocker PreToolUse hook."""
+
+import importlib.util
+import pathlib
+import sys
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "gh_body_arg_blocker",
+    _HOOK_DIR / "gh-body-arg-blocker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+_uses_body_string_arg = hook_module._uses_body_string_arg
+
+
+def test_blocks_issue_create_with_body_string() -> None:
+    assert _uses_body_string_arg('gh issue create --title "T" --body "text"')
+
+
+def test_blocks_issue_edit_with_body_string() -> None:
+    assert _uses_body_string_arg('gh issue edit 42 --body "updated text"')
+
+
+def test_blocks_issue_comment_with_body_string() -> None:
+    assert _uses_body_string_arg('gh issue comment 42 --body "my comment"')
+
+
+def test_blocks_pr_create_with_body_string() -> None:
+    assert _uses_body_string_arg('gh pr create --title "T" --body "desc"')
+
+
+def test_blocks_pr_edit_with_body_string() -> None:
+    assert _uses_body_string_arg('gh pr edit 10 --body "new desc"')
+
+
+def test_blocks_pr_comment_with_body_string() -> None:
+    assert _uses_body_string_arg('gh pr comment 10 --body "LGTM"')
+
+
+def test_blocks_pr_review_with_body_string() -> None:
+    assert _uses_body_string_arg('gh pr review 10 --approve --body "looks good"')
+
+
+def test_blocks_short_b_flag() -> None:
+    assert _uses_body_string_arg('gh pr create --title "T" -b "desc"')
+
+
+def test_blocks_pr_create_with_body_equals_syntax() -> None:
+    assert _uses_body_string_arg('gh pr create --title "T" --body="text"')
+
+
+def test_blocks_pr_create_with_short_b_equals_syntax() -> None:
+    assert _uses_body_string_arg('gh pr create --title "T" -b="text"')
+
+
+def test_blocks_multiline_bash_continuation_body_on_later_line() -> None:
+    command = 'gh pr create \\\n  --title "T" \\\n  --body "text"\n'
+    assert _uses_body_string_arg(command)
+
+
+def test_blocks_multiline_continuation_with_trailing_whitespace() -> None:
+    """Continuation marker followed by trailing spaces must still join lines."""
+    command = 'gh pr create \\   \n  --title "T" \\   \n  --body "text"\n'
+    assert _uses_body_string_arg(command)
+
+
+def test_blocks_multiline_powershell_continuation_body_on_later_line() -> None:
+    """PowerShell backtick continuation lines must be joined before tokenizing."""
+    command = 'gh pr create `\n  --title "T" `\n  --body "text"\n'
+    assert _uses_body_string_arg(command)
+
+
+def test_blocks_multiline_powershell_continuation_with_trailing_whitespace() -> None:
+    """PowerShell backtick continuation with trailing spaces must still join."""
+    command = 'gh pr create `   \n  --title "T" `   \n  --body "text"\n'
+    assert _uses_body_string_arg(command)
+
+
+def test_approves_body_file() -> None:
+    assert not _uses_body_string_arg(
+        'gh pr create --title "T" --body-file /tmp/body.md'
+    )
+
+
+def test_approves_body_file_equals_syntax() -> None:
+    assert not _uses_body_string_arg(
+        'gh pr create --title "T" --body-file=/tmp/body.md'
+    )
+
+
+def test_approves_issue_create_with_body_file() -> None:
+    assert not _uses_body_string_arg(
+        'gh issue create --title "T" --body-file /tmp/body.md'
+    )
+
+
+def test_approves_unrelated_gh_command() -> None:
+    assert not _uses_body_string_arg("gh pr list --repo owner/repo")
+
+
+def test_approves_gh_pr_merge() -> None:
+    assert not _uses_body_string_arg("gh pr merge 10 --squash")
+
+
+def test_approves_empty_command() -> None:
+    assert not _uses_body_string_arg("")
+
+
+def test_no_false_positive_body_in_title_value() -> None:
+    """--body inside a quoted --title value must not trigger."""
+    assert not _uses_body_string_arg(
+        'gh pr create --title "block gh --body string arg" --body-file /tmp/b.md'
+    )
+
+
+def test_no_false_positive_body_as_title_value() -> None:
+    """--title "--body" must not trigger; posix=False retains quotes so the value is not a bare flag."""
+    assert not _uses_body_string_arg(
+        'gh pr create --title "--body" --body-file /tmp/b.md'
+    )
+
+
+def test_no_false_positive_windows_path_in_body_file() -> None:
+    """Unquoted Windows path with backslashes in --body-file must be approved without token corruption."""
+    assert not _uses_body_string_arg(
+        r'gh pr create --title "T" --body-file C:\Users\jon\tmp\body.md'
+    )
+
+
+def test_no_false_positive_heredoc_body_text() -> None:
+    """Multiline command where body content mentions --body must not trigger."""
+    command = (
+        "gh pr create --title 'My PR' --body-file /tmp/body.md\n"
+        "# body content below mentions --body for documentation\n"
+        '# Use --body-file not --body "string"\n'
+    )
+    assert not _uses_body_string_arg(command)
+
+
+def test_no_false_positive_unparseable_command() -> None:
+    """Unparseable first line (unmatched quote) falls back to approve."""
+    assert not _uses_body_string_arg("gh pr create --title 'unmatched --body oops")

package/hooks/blocking/test_pr_description_enforcer.py

@@ -0,0 +1,187 @@
+"""Unit tests for pr-description-enforcer PreToolUse hook."""
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+from unittest.mock import patch
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+from _gh_body_arg_utils import get_logical_first_line
+
+hook_spec = importlib.util.spec_from_file_location(
+    "pr_description_enforcer",
+    _HOOK_DIR / "pr-description-enforcer.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+extract_body_from_command = hook_module.extract_body_from_command
+validate_pr_body = hook_module.validate_pr_body
+
+VALID_BODY = (
+    "## Description\n\nThis PR fixes a real bug.\n\n"
+    "## Why\n\nBecause it was broken in production.\n\n"
+    "## How\n\nRefactored the auth module to handle edge cases correctly.\n"
+)
+
+
+def test_extract_body_from_body_string() -> None:
+    command = 'gh pr create --title "T" --body "Description and some text."'
+    assert "Description" in extract_body_from_command(command)
+
+
+def test_extract_body_from_body_file_space_form(tmp_path: pathlib.Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text(VALID_BODY)
+    command = f'gh pr create --title "T" --body-file {body_file}'
+    assert extract_body_from_command(command) == VALID_BODY
+
+
+def test_extract_body_from_body_file_equals_form(tmp_path: pathlib.Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text(VALID_BODY)
+    command = f'gh pr create --title "T" --body-file="{body_file}"'
+    assert extract_body_from_command(command) == VALID_BODY
+
+
+def test_extract_body_from_body_file_equals_form_with_spaces(
+    tmp_path: pathlib.Path,
+) -> None:
+    """Quoted --body-file=VALUE with spaces in path must be reassembled, not truncated."""
+    body_file = tmp_path / "my body with spaces.md"
+    body_file.write_text(VALID_BODY)
+    command = f'gh pr create --title "T" --body-file="{body_file}"'
+    assert extract_body_from_command(command) == VALID_BODY
+
+
+def test_extract_body_file_missing_path_returns_none() -> None:
+    command = 'gh pr create --title "T" --body-file /nonexistent/path.md'
+    assert extract_body_from_command(command) is None
+
+
+def test_extract_body_file_shell_variable_returns_empty() -> None:
+    """Shell variables like $bodyPath can't be resolved at hook time -- approve safely."""
+    command = 'gh pr create --title "T" --body-file $bodyPath'
+    assert extract_body_from_command(command) == ""
+
+
+def test_extract_body_file_no_false_positive_in_title() -> None:
+    command = 'gh pr create --title "use --body-file /tmp/x.md" --body "actual body"'
+    extracted_body = extract_body_from_command(command)
+    assert extracted_body == "actual body"
+
+
+def test_no_false_positive_body_in_title_string_value() -> None:
+    command = 'gh pr create --title \'use --body "x"\' --body "actual body"'
+    assert extract_body_from_command(command) == "actual body"
+
+
+def test_extract_body_from_body_equals_double_quote_form() -> None:
+    command = 'gh pr create --title "T" --body="Some body text here."'
+    assert extract_body_from_command(command) == "Some body text here."
+
+
+def test_extract_body_from_body_equals_single_quote_form() -> None:
+    command = "gh pr create --title 'T' --body='Some body text here.'"
+    assert extract_body_from_command(command) == "Some body text here."
+
+
+def test_extract_body_equals_shell_var_returns_empty() -> None:
+    """Shell variable like --body=$bodyText cannot be resolved at hook time -- approve safely."""
+    command = 'gh pr create --title "T" --body=$bodyText'
+    assert extract_body_from_command(command) == ""
+
+
+def test_extract_short_flag_equals_form() -> None:
+    command = 'gh pr create --title "T" -b="Some body text here."'
+    assert extract_body_from_command(command) == "Some body text here."
+
+
+def test_extract_short_flag_shell_var_returns_empty() -> None:
+    """Shell variable like -b=$var cannot be resolved at hook time -- approve safely."""
+    command = 'gh pr create --title "T" -b=$bodyVar'
+    assert extract_body_from_command(command) == ""
+
+
+def test_validate_passes_complete_body() -> None:
+    assert validate_pr_body(VALID_BODY) == []
+
+
+def test_validate_blocks_missing_sections() -> None:
+    violations = validate_pr_body("Some body text without required sections.\n" * 5)
+    assert any(
+        "Missing required section" in each_violation for each_violation in violations
+    )
+
+
+def test_validate_blocks_vague_language() -> None:
+    body = VALID_BODY + "\nFixed bug in the auth module.\n"
+    violations = validate_pr_body(body)
+    assert any("Vague language" in each_violation for each_violation in violations)
+
+
+def test_validate_blocks_short_body() -> None:
+    violations = validate_pr_body("Too short.")
+    assert any("too short" in each_violation.lower() for each_violation in violations)
+
+
+def test_body_file_content_validated(tmp_path: pathlib.Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text("Too short.")
+    body = extract_body_from_command(
+        f'gh pr create --title "T" --body-file {body_file}'
+    )
+    assert body == "Too short."
+    violations = validate_pr_body(body)
+    assert violations
+
+
+def test_extract_body_string_value_skips_body_file_path_token() -> None:
+    command = 'gh pr create --body-file --body "actual text"'
+    assert extract_body_from_command(command) is None
+
+
+def test_get_logical_first_line_does_not_join_bash_command_substitution() -> None:
+    command = 'VAR=`cmd`\ngh pr create --body "text"'
+    assert get_logical_first_line(command) == "VAR=`cmd`"
+
+
+def test_get_logical_first_line_joins_powershell_backtick_continuation() -> None:
+    command = 'Some-Command -Param `\n"value"'
+    assert get_logical_first_line(command) == 'Some-Command -Param "value"'
+
+
+def test_main_does_not_block_when_dash_b_only_appears_in_word() -> None:
+    hook_input = {
+        "tool_name": "Bash",
+        "tool_input": {"command": 'gh pr create --title "fix sub-branch handling"'},
+    }
+    captured_stdout = io.StringIO()
+    with patch("sys.stdin", io.StringIO(json.dumps(hook_input))):
+        with patch("sys.stdout", captured_stdout):
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+    assert "deny" not in captured_stdout.getvalue()
+
+
+def test_main_does_not_block_when_no_body_flag_present() -> None:
+    hook_input = {
+        "tool_name": "Bash",
+        "tool_input": {"command": 'gh pr create --title "My PR"'},
+    }
+    captured_stdout = io.StringIO()
+    with patch("sys.stdin", io.StringIO(json.dumps(hook_input))):
+        with patch("sys.stdout", captured_stdout):
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+    assert "deny" not in captured_stdout.getvalue()

package/hooks/lifecycle/test_config_change_guard.py

@@ -0,0 +1,111 @@
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+HOOK_PATH = Path(__file__).parent / "config-change-guard.py"
+
+
+def _run_hook(
+    source: str,
+    file_path: str,
+    extra_env: dict[str, str] | None = None,
+) -> subprocess.CompletedProcess[str]:
+    payload = {"source": source, "file_path": file_path}
+    env = {**os.environ, **(extra_env or {})}
+    return subprocess.run(
+        [sys.executable, str(HOOK_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=env,
+    )
+
+
+def _make_settings_with_hook_count(hook_count: int, tmp_path: Path) -> str:
+    hooks_list = [
+        {"type": "command", "command": f"hook_{each_index}.py"}
+        for each_index in range(hook_count)
+    ]
+    settings = {"hooks": {"PreToolUse": [{"hooks": hooks_list}]}}
+    settings_file = tmp_path / "settings.json"
+    settings_file.write_text(json.dumps(settings))
+    return str(settings_file)
+
+
+def test_hook_count_increase_emits_user_visible_output(tmp_path: Path) -> None:
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("2")
+    settings_path = _make_settings_with_hook_count(5, tmp_path)
+
+    hook_run = _run_hook(
+        source="user_settings",
+        file_path=settings_path,
+        extra_env={"KNOWN_HOOK_COUNT_FILE": str(known_count_file)},
+    )
+
+    assert hook_run.returncode == 0
+    assert hook_run.stderr.strip() == ""
+    block_payload = json.loads(hook_run.stdout)
+    assert block_payload["decision"] == "block"
+    assert "2" in block_payload["reason"] and "5" in block_payload["reason"]
+    assert block_payload["hookSpecificOutput"]["hookEventName"] == "ConfigChange"
+    assert "hook" in block_payload["hookSpecificOutput"]["additionalContext"].lower()
+
+
+def test_hook_count_stable_produces_no_output(tmp_path: Path) -> None:
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("3")
+    settings_path = _make_settings_with_hook_count(3, tmp_path)
+
+    hook_run = _run_hook(
+        source="user_settings",
+        file_path=settings_path,
+        extra_env={"KNOWN_HOOK_COUNT_FILE": str(known_count_file)},
+    )
+
+    assert hook_run.returncode == 0
+    assert hook_run.stderr.strip() == ""
+    assert hook_run.stdout.strip() == ""
+
+
+def test_hook_count_decrease_produces_no_output(tmp_path: Path) -> None:
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("5")
+    settings_path = _make_settings_with_hook_count(3, tmp_path)
+
+    hook_run = _run_hook(
+        source="user_settings",
+        file_path=settings_path,
+        extra_env={"KNOWN_HOOK_COUNT_FILE": str(known_count_file)},
+    )
+
+    assert hook_run.returncode == 0
+    assert hook_run.stderr.strip() == ""
+    assert hook_run.stdout.strip() == ""
+
+
+def test_hook_count_increase_blocks_on_second_invocation(tmp_path: Path) -> None:
+    known_count_file = tmp_path / "known-hook-count.txt"
+    known_count_file.write_text("2")
+    settings_path = _make_settings_with_hook_count(5, tmp_path)
+    extra_env = {"KNOWN_HOOK_COUNT_FILE": str(known_count_file)}
+
+    first_run = _run_hook("user_settings", settings_path, extra_env)
+    assert first_run.returncode == 0
+    assert first_run.stdout.strip() != ""
+
+    second_run = _run_hook("user_settings", settings_path, extra_env)
+    assert second_run.returncode == 0
+    assert second_run.stdout.strip() != ""
+
+
+def test_non_user_settings_source_produces_no_output(tmp_path: Path) -> None:
+    settings_path = _make_settings_with_hook_count(10, tmp_path)
+    hook_run = _run_hook(source="system", file_path=settings_path)
+    assert hook_run.returncode == 0
+    assert hook_run.stderr.strip() == ""
+    assert hook_run.stdout.strip() == ""

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.21.1",
+    "version": "1.22.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {