claude-dev-env 2.18.0 → 2.20.0

package/hooks/blocking/test_session_edit_stage_gate_support.py

@@ -0,0 +1,204 @@
+"""Production-neutral fixtures for session-edit stage gate tests."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+_SUPPORT_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_TREE = _SUPPORT_DIRECTORY.parent
+if str(_HOOKS_TREE) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_TREE))
+
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    ALL_EDITED_FILE_PATHS_KEY,
+    SESSION_EDIT_FILE_PREFIX,
+    SESSION_EDIT_FILE_SUFFIX,
+)
+
+
+def clean_git_environment() -> dict[str, str]:
+    """Return the environment without inherited repository overrides."""
+    return {
+        each_key: each_value
+        for each_key, each_value in os.environ.items()
+        if not each_key.startswith("GIT_")
+    }
+
+
+def run_git(repository_root: Path, *git_arguments: str) -> None:
+    """Run one Git command in a test repository."""
+    subprocess.run(
+        ["git", "-C", str(repository_root), *git_arguments],
+        check=True,
+        capture_output=True,
+        env=clean_git_environment(),
+    )
+
+
+def initialize_repository(repository_root: Path) -> None:
+    """Create a Git repository on a non-protected test branch."""
+    run_git(repository_root, "init")
+    run_git(repository_root, "checkout", "-b", "test-session-stage")
+    run_git(repository_root, "config", "user.email", "tests@example.com")
+    run_git(repository_root, "config", "user.name", "Gate Tests")
+
+
+def prepare_repository_with_unstaged_edit(repository_root: Path) -> Path:
+    """Create one tracked file with an unstaged edit."""
+    initialize_repository(repository_root)
+    tracked_file = repository_root / "widget.py"
+    tracked_file.write_text("x = 1\n", encoding="utf-8")
+    run_git(repository_root, "add", "widget.py")
+    run_git(repository_root, "commit", "-m", "add widget")
+    tracked_file.write_text("x = 2\n", encoding="utf-8")
+    return tracked_file
+
+
+def prepare_repository_with_two_unstaged_edits(repository_root: Path) -> tuple[Path, Path]:
+    """Create two tracked files with separate unstaged edits."""
+    initialize_repository(repository_root)
+    tracked_file = repository_root / "widget.py"
+    second_file = repository_root / "second_widget.py"
+    tracked_file.write_text("x = 1\n", encoding="utf-8")
+    second_file.write_text("y = 1\n", encoding="utf-8")
+    run_git(repository_root, "add", "widget.py", "second_widget.py")
+    run_git(repository_root, "commit", "-m", "add widgets")
+    tracked_file.write_text("x = 2\n", encoding="utf-8")
+    second_file.write_text("y = 2\n", encoding="utf-8")
+    return tracked_file, second_file
+
+
+def make_test_directories(tmp_path: Path) -> tuple[Path, Path, Path]:
+    """Create repository, tracker, and home directories for one test."""
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    temp_directory = tmp_path / "tmp"
+    temp_directory.mkdir()
+    home_directory = tmp_path / "home"
+    home_directory.mkdir()
+    return repository_root, temp_directory, home_directory
+
+
+def make_process_repository(tmp_path: Path) -> Path:
+    """Create a separate Git repository for the dispatcher process directory."""
+    process_repository = tmp_path / "process-repository"
+    process_repository.mkdir()
+    initialize_repository(process_repository)
+    return process_repository
+
+
+def prepare_process_child_repository(process_repository: Path) -> None:
+    """Create the relative command directory inside process repository B."""
+    process_child_repository = process_repository / "child"
+    process_child_repository.mkdir()
+    initialize_repository(process_child_repository)
+
+
+def build_hook_environment(
+    temp_directory: Path,
+    home_directory: Path,
+) -> dict[str, str]:
+    """Build isolated environment variables for production hooks."""
+    environment = clean_git_environment()
+    environment["TMP"] = str(temp_directory)
+    environment["TEMP"] = str(temp_directory)
+    environment["TMPDIR"] = str(temp_directory)
+    environment["USERPROFILE"] = str(home_directory)
+    environment["HOME"] = str(home_directory)
+    return environment
+
+
+def run_production_hook(
+    hook_path: Path,
+    payload: str,
+    repository_root: Path,
+    temp_directory: Path,
+    home_directory: Path,
+    process_directory: Path | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run one hook script as a production subprocess."""
+    return subprocess.run(
+        [sys.executable, str(hook_path)],
+        check=False,
+        input=payload,
+        capture_output=True,
+        text=True,
+        cwd=str(process_directory or repository_root),
+        env=build_hook_environment(temp_directory, home_directory),
+        timeout=60,
+    )
+
+
+def run_tracker_event(
+    tracked_file: Path,
+    session_id: str,
+    repository_root: Path,
+    temp_directory: Path,
+    home_directory: Path,
+) -> subprocess.CompletedProcess[str]:
+    """Run the production PostToolUse tracker for one edited file."""
+    payload = json.dumps(
+        {
+            "tool_name": "Edit",
+            "session_id": session_id,
+            "tool_input": {"file_path": str(tracked_file)},
+        }
+    )
+    return run_production_hook(
+        _HOOKS_TREE / "observability" / "session_file_edit_tracker.py",
+        payload,
+        repository_root,
+        temp_directory,
+        home_directory,
+    )
+
+
+def run_bash_dispatcher(
+    bash_command: str,
+    session_id: str,
+    repository_root: Path,
+    temp_directory: Path,
+    home_directory: Path,
+    process_directory: Path | None = None,
+) -> subprocess.CompletedProcess[str]:
+    """Run the production Bash PreToolUse dispatcher for one command."""
+    payload = json.dumps(
+        {
+            "tool_name": "Bash",
+            "cwd": str(repository_root),
+            "session_id": session_id,
+            "tool_input": {"command": bash_command},
+        }
+    )
+    return run_production_hook(
+        _SUPPORT_DIRECTORY / "bash_pre_tool_use_dispatcher.py",
+        payload,
+        repository_root,
+        temp_directory,
+        home_directory,
+        process_directory,
+    )
+
+
+def read_tracker_paths(temp_directory: Path, session_id: str) -> list[str]:
+    """Read the recorded paths from one production tracker file."""
+    tracker_file = (
+        temp_directory / f"{SESSION_EDIT_FILE_PREFIX}{session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    )
+    tracker_payload = json.loads(tracker_file.read_text(encoding="utf-8"))
+    return tracker_payload[ALL_EDITED_FILE_PATHS_KEY]
+
+
+def parse_dispatcher_decision(stdout_text: str) -> tuple[str, str]:
+    """Return the dispatcher decision and reason from its stdout payload."""
+    if not stdout_text.strip():
+        return "", ""
+    hook_specific_output = json.loads(stdout_text)["hookSpecificOutput"]
+    return (
+        hook_specific_output.get("permissionDecision", ""),
+        hook_specific_output.get("permissionDecisionReason", ""),
+    )

package/hooks/blocking/test_session_edit_stage_gate_tracker.py

@@ -0,0 +1,116 @@
+"""Production-path tracker event-order tests for the session-edit stage gate."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_TEST_DIRECTORY = Path(__file__).resolve().parent
+if str(_TEST_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_TEST_DIRECTORY))
+
+from test_session_edit_stage_gate_support import (  # noqa: E402
+    make_test_directories,
+    make_process_repository,
+    parse_dispatcher_decision,
+    prepare_process_child_repository,
+    prepare_repository_with_unstaged_edit,
+    prepare_repository_with_two_unstaged_edits,
+    read_tracker_paths,
+    run_bash_dispatcher,
+    run_tracker_event,
+)
+
+SESSION_ID = "tracker-production-session"
+
+
+def test_tracker_events_precede_dispatcher_stage_decision(tmp_path: Path) -> None:
+    """The dispatcher sees every edit recorded before the commit event."""
+    repository_root, temp_directory, home_directory = make_test_directories(tmp_path)
+    tracked_file, second_file = prepare_repository_with_two_unstaged_edits(repository_root)
+    for each_file in (tracked_file, second_file):
+        tracker_run = run_tracker_event(
+            each_file, SESSION_ID, repository_root, temp_directory, home_directory
+        )
+        assert tracker_run.returncode == 0
+
+    assert read_tracker_paths(temp_directory, SESSION_ID) == [
+        str(tracked_file.resolve()),
+        str(second_file.resolve()),
+    ]
+
+    dispatcher_run = run_bash_dispatcher(
+        "git commit -m update",
+        SESSION_ID,
+        repository_root,
+        temp_directory,
+        home_directory,
+    )
+    assert dispatcher_run.returncode == 0
+    decision, reason = parse_dispatcher_decision(dispatcher_run.stdout)
+    assert decision == "deny"
+    assert "widget.py" in reason
+    assert "second_widget.py" in reason
+
+
+def test_dispatcher_uses_event_cwd_when_process_runs_elsewhere(tmp_path: Path) -> None:
+    """The dispatcher passes event cwd so the gate inspects the event repository."""
+    repository_root, temp_directory, home_directory = make_test_directories(tmp_path)
+    process_repository = make_process_repository(tmp_path)
+    tracked_file = prepare_repository_with_unstaged_edit(repository_root)
+    tracker_run = run_tracker_event(
+        tracked_file, SESSION_ID, repository_root, temp_directory, home_directory
+    )
+    assert tracker_run.returncode == 0
+
+    dispatcher_run = run_bash_dispatcher(
+        "git commit -m update",
+        SESSION_ID,
+        repository_root,
+        temp_directory,
+        home_directory,
+        process_directory=process_repository,
+    )
+    assert dispatcher_run.returncode == 0
+    decision, reason = parse_dispatcher_decision(dispatcher_run.stdout)
+    assert decision == "deny"
+    assert "widget.py" in reason
+
+
+@pytest.mark.parametrize(
+    "bash_command",
+    [
+        "cd child && git commit -m update",
+        "pushd child && git commit -m update",
+        "git -C child commit -m update",
+    ],
+)
+def test_dispatcher_anchors_relative_command_directory_to_event_cwd(
+    tmp_path: Path,
+    bash_command: str,
+) -> None:
+    """Relative commit directories resolve from event cwd across command forms."""
+    repository_root, temp_directory, home_directory = make_test_directories(tmp_path)
+    process_repository = make_process_repository(tmp_path)
+    prepare_process_child_repository(process_repository)
+    (repository_root / "child").mkdir()
+    tracked_file = prepare_repository_with_unstaged_edit(repository_root)
+    tracker_run = run_tracker_event(
+        tracked_file, SESSION_ID, repository_root, temp_directory, home_directory
+    )
+    assert tracker_run.returncode == 0
+
+    dispatcher_run = run_bash_dispatcher(
+        bash_command,
+        SESSION_ID,
+        repository_root,
+        temp_directory,
+        home_directory,
+        process_directory=process_repository,
+    )
+    assert dispatcher_run.returncode == 0
+    decision, reason = parse_dispatcher_decision(dispatcher_run.stdout)
+    assert decision == "deny"
+    assert "widget.py" in reason

package/hooks/blocking/test_shared_stdin_adoption.py

@@ -26,6 +26,13 @@ from pathlib import Path
 import pytest
 
 _BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+if str(_BLOCKING_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIRECTORY))
+
+from test_hook_subprocess_support import (  # noqa: E402
+    assert_hook_deny_log_contains,
+    run_hook_as_subprocess,
+)
 
 ALL_CONVERTED_HOOK_FILENAMES = (
     "open_questions_in_plans_blocker.py",
@@ -48,15 +55,15 @@ ALL_FAIL_SOFT_PAYLOADS = (
 )
 
 
-def _run_hook_script(hook_filename: str, stdin_text: str) -> subprocess.CompletedProcess:
+def _run_hook_script(
+    hook_filename: str, stdin_text: str, temporary_home_directory: Path
+) -> subprocess.CompletedProcess[str]:
     hook_script_path = _BLOCKING_DIRECTORY / hook_filename
-    return subprocess.run(
-        [sys.executable, str(hook_script_path)],
-        input=stdin_text,
-        capture_output=True,
-        text=True,
-        check=False,
-        cwd=str(Path.home()),
+    return run_hook_as_subprocess(
+        hook_script_path=hook_script_path,
+        payload_text=stdin_text,
+        working_directory=temporary_home_directory,
+        home_directory=temporary_home_directory,
     )
 
 
@@ -69,8 +76,10 @@ def _decision_from_stdout(completed: subprocess.CompletedProcess) -> str | None:
 
 @pytest.mark.parametrize("hook_filename", ALL_CONVERTED_HOOK_FILENAMES)
 @pytest.mark.parametrize("stdin_text", ALL_FAIL_SOFT_PAYLOADS)
-def test_fail_soft_payload_exits_zero_with_no_decision(hook_filename: str, stdin_text: str) -> None:
-    completed = _run_hook_script(hook_filename, stdin_text)
+def test_fail_soft_payload_exits_zero_with_no_decision(
+    hook_filename: str, stdin_text: str, tmp_path: Path
+) -> None:
+    completed = _run_hook_script(hook_filename, stdin_text, tmp_path)
     assert completed.returncode == 0, (
         f"{hook_filename} must exit zero on fail-soft stdin; "
         f"got code {completed.returncode}, stderr {completed.stderr!r}"
@@ -93,9 +102,10 @@ def test_open_questions_blocker_still_denies_plan_with_open_questions(
             "tool_input": {"file_path": str(plan_path), "content": plan_body},
         }
     )
-    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload)
-    assert completed.returncode == 0
+    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload, tmp_path)
+    assert completed.returncode == 0, completed.stderr
     assert _decision_from_stdout(completed) == "deny"
+    assert_hook_deny_log_contains(tmp_path, "open_questions_in_plans_blocker.py")
 
 
 def test_open_questions_blocker_still_allows_plan_without_open_questions(
@@ -111,8 +121,8 @@ def test_open_questions_blocker_still_allows_plan_without_open_questions(
             "tool_input": {"file_path": str(plan_path), "content": plan_body},
         }
     )
-    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload)
-    assert completed.returncode == 0
+    completed = _run_hook_script("open_questions_in_plans_blocker.py", payload, tmp_path)
+    assert completed.returncode == 0, completed.stderr
     assert _decision_from_stdout(completed) is None
 
 
@@ -130,9 +140,10 @@ def test_package_inventory_blocker_still_denies_uninventoried_new_file(
             "tool_input": {"file_path": str(new_file_path), "content": "x = 1\n"},
         }
     )
-    completed = _run_hook_script("package_inventory_stale_blocker.py", payload)
-    assert completed.returncode == 0
+    completed = _run_hook_script("package_inventory_stale_blocker.py", payload, tmp_path)
+    assert completed.returncode == 0, completed.stderr
     assert _decision_from_stdout(completed) == "deny"
+    assert_hook_deny_log_contains(tmp_path, "package_inventory_stale_blocker.py")
 
 
 def test_package_inventory_blocker_still_allows_inventoried_new_file(
@@ -152,15 +163,15 @@ def test_package_inventory_blocker_still_allows_inventoried_new_file(
             "tool_input": {"file_path": str(new_file_path), "content": "x = 1\n"},
         }
     )
-    completed = _run_hook_script("package_inventory_stale_blocker.py", payload)
-    assert completed.returncode == 0
+    completed = _run_hook_script("package_inventory_stale_blocker.py", payload, tmp_path)
+    assert completed.returncode == 0, completed.stderr
     assert _decision_from_stdout(completed) is None
 
 
-def test_converted_hooks_allow_unrelated_tool_name() -> None:
+def test_converted_hooks_allow_unrelated_tool_name(tmp_path: Path) -> None:
     payload = json.dumps({"tool_name": "Bash", "tool_input": {"command": "ls"}})
     for each_hook_filename in ALL_CONVERTED_HOOK_FILENAMES:
-        completed = _run_hook_script(each_hook_filename, payload)
+        completed = _run_hook_script(each_hook_filename, payload, tmp_path)
         assert completed.returncode == 0, (
             f"{each_hook_filename} must exit zero on an unrelated tool; stderr {completed.stderr!r}"
         )

package/hooks/blocking/test_test_preflight_check.py

@@ -0,0 +1,80 @@
+"""Production-path tests for pytest-Django and Playwright preflight selection."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+_DISPATCHER_PATH = _BLOCKING_DIRECTORY / "bash_pre_tool_use_dispatcher.py"
+if str(_BLOCKING_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIRECTORY))
+
+from test_hook_subprocess_support import (  # noqa: E402
+    build_bash_payload,
+    read_hook_permission_decision,
+    run_hook_as_subprocess,
+)
+
+
+def _run_bash_dispatch(
+    command: str, project_root: Path
+) -> subprocess.CompletedProcess[str]:
+    return run_hook_as_subprocess(
+        hook_script_path=_DISPATCHER_PATH,
+        payload_text=build_bash_payload(command),
+        working_directory=project_root,
+        home_directory=project_root,
+        environment_updates_by_name={"PWD": str(project_root)},
+    )
+
+
+def _create_django_project_fixture(tmp_path: Path) -> Path:
+    project_root = tmp_path / "django-project"
+    project_root.mkdir()
+    (project_root / "manage.py").write_text(
+        "import sys\n\nif __name__ == '__main__':\n    sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    return project_root
+
+
+def test_dispatcher_selects_pytest_django_changed_test(tmp_path: Path) -> None:
+    project_root = _create_django_project_fixture(tmp_path)
+
+    command = "python -m pytest tests/test_models.py"
+    completed_process = _run_bash_dispatch(command, project_root)
+
+    assert completed_process.returncode == 0, completed_process.stderr
+    decision, reason = read_hook_permission_decision(completed_process.stdout)
+    assert decision == "deny"
+    assert "No database file (db.sqlite3)" in reason
+
+
+def test_dispatcher_ignores_unrecognized_django_test_runner(tmp_path: Path) -> None:
+    project_root = _create_django_project_fixture(tmp_path)
+
+    command = "python -m unittest tests/test_models.py"
+    completed_process = _run_bash_dispatch(command, project_root)
+
+    assert completed_process.returncode == 0, completed_process.stderr
+    assert completed_process.stdout == ""
+
+
+def test_dispatcher_selects_playwright_changed_spec(tmp_path: Path) -> None:
+    command = "npx playwright test tests/account.spec.ts --base-url http://127.0.0.1:1"
+    completed_process = _run_bash_dispatch(command, tmp_path)
+
+    assert completed_process.returncode == 0, completed_process.stderr
+    decision, reason = read_hook_permission_decision(completed_process.stdout)
+    assert decision == "deny"
+    assert "Server at http://127.0.0.1:1 is unreachable" in reason
+
+
+def test_dispatcher_ignores_non_playwright_test_runner(tmp_path: Path) -> None:
+    command = "node tests/account.spec.ts"
+    completed_process = _run_bash_dispatch(command, tmp_path)
+
+    assert completed_process.returncode == 0, completed_process.stderr
+    assert completed_process.stdout == ""

package/hooks/git-hooks/AGENTS.md

@@ -6,7 +6,7 @@ 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_commit.py` | `pre-commit` | Runs immediate CODE_RULES and terminology validation over staged changes; exits 1 when any staged file has a blocking violation. CI runs package tests for package Python changes. |
 | `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 |

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

@@ -10,6 +10,7 @@ import ...`` resolve against this file both inside the repo and under
 from __future__ import annotations
 
 STAGED_SCOPE_ARGUMENT: str = "--staged"
+IMMEDIATE_SCOPE_ARGUMENT: str = "--immediate"
 BASE_REFERENCE_ARGUMENT: str = "--base"
 DEFAULT_REMOTE_BASE_REFERENCE: str = "origin/HEAD"
 ALL_ZEROS_OBJECT_NAME_CHARACTER: str = "0"