claude-dev-env 1.26.5 → 1.28.0

package/hooks/blocking/tdd_enforcer.py

@@ -6,12 +6,19 @@ Blocks writes to production source files when no matching test exists
 or the matching test has not been modified within the configured
 freshness window. Enforces "TDD IS NON-NEGOTIABLE" from CLAUDE.md.
 """
+import ast
 import json
 import re
 import sys
 import time
 from pathlib import Path
 
+_hooks_root_path_string = str(Path(__file__).resolve().parent.parent)
+if _hooks_root_path_string not in sys.path:
+    sys.path.insert(0, _hooks_root_path_string)
+
+from config.messages import USER_FACING_TDD_NOTICE
+
 PRODUCTION_EXTENSIONS = {'.py', '.ts', '.tsx', '.js', '.jsx'}
 SKIP_PATTERNS = {
     'test_', '_test.', '.test.', 'tests/', '__tests__/',
@@ -33,8 +40,41 @@ def _freshness_seconds() -> int:
     return 600
 
 
-def _bypass_sentinel() -> str:
-    return "# pragma: no-tdd-gate"
+def _constants_only_allowed_node_types() -> tuple[type, ...]:
+    return (
+        ast.Import,
+        ast.ImportFrom,
+        ast.Assign,
+        ast.AnnAssign,
+    )
+
+
+def _is_module_docstring_expression(module_level_node: ast.stmt) -> bool:
+    if not isinstance(module_level_node, ast.Expr):
+        return False
+    expression_value = module_level_node.value
+    if not isinstance(expression_value, ast.Constant):
+        return False
+    return isinstance(expression_value.value, str)
+
+
+def _is_constants_only_python_content(content: str) -> bool:
+    if not content.strip():
+        return False
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return False
+    if not parsed_tree.body:
+        return False
+    allowed_node_types = _constants_only_allowed_node_types()
+    for each_top_level_node in parsed_tree.body:
+        if isinstance(each_top_level_node, allowed_node_types):
+            continue
+        if _is_module_docstring_expression(each_top_level_node):
+            continue
+        return False
+    return True
 
 
 def _tests_directory_name() -> str:
@@ -154,13 +194,17 @@ def has_fresh_test(
 
 def build_deny_reason(production_path: Path, all_candidates: list[Path]) -> str:
     candidate_lines = "\n".join(f"  - {each_path}" for each_path in all_candidates)
+    hook_source_path = Path(__file__).resolve()
     return (
         f"[TDD] Blocking write to production file: {production_path}\n"
         f"No matching test file exists, or it has not been modified within the last "
         f"{_freshness_seconds()} seconds.\n"
         f"Expected one of:\n{candidate_lines}\n"
-        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n"
-        f"Bypass (discouraged): include the sentinel '{_bypass_sentinel()}' in the file content."
+        f"Write a failing test first (RED), then the minimum code to pass it (GREEN).\n\n"
+        f"If this file legitimately does not need a test (for example, a module containing only "
+        f"module-level constants with no behavior), that is a hook enhancement, not a bypass. "
+        f"Propose an exemption rule in {hook_source_path} so every similar file benefits "
+        f"automatically. Do not add escape-hatch markers to production files."
     )
 
 
@@ -180,7 +224,9 @@ def emit_deny(reason: str) -> None:
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
             "permissionDecisionReason": reason,
-        }
+        },
+        "suppressOutput": True,
+        "systemMessage": USER_FACING_TDD_NOTICE,
     }
     print(json.dumps(deny_payload))
 
@@ -252,7 +298,7 @@ def main() -> None:
 
     # Block production code - require confirmation
     written_content = _extract_written_content(tool_name, tool_input)
-    if _bypass_sentinel() in written_content:
+    if tool_name == "Write" and ext == ".py" and _is_constants_only_python_content(written_content):
         emit_allow()
         sys.exit(0)
 

package/hooks/blocking/test_destructive_command_blocker.py

@@ -4,6 +4,7 @@ import json
 import os
 import subprocess
 import sys
+import tempfile
 from pathlib import Path
 
 
@@ -165,3 +166,171 @@ def test_rm_rf_still_asks_when_redirect_env_var_is_unset() -> None:
 
     response = json.loads(result.stdout)
     assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def _run_hook_with_fake_home(
+    payload: dict,
+    fake_home: Path,
+    working_directory: Path,
+    disable_ephemeral_auto_allow: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    child_environment = os.environ.copy()
+    child_environment.pop(GH_REDIRECT_ACTIVE_ENV_VAR, None)
+    child_environment["HOME"] = str(fake_home)
+    child_environment["USERPROFILE"] = str(fake_home)
+    if disable_ephemeral_auto_allow:
+        child_environment["CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW"] = "1"
+    else:
+        child_environment.pop("CLAUDE_DESTRUCTIVE_DISABLE_EPHEMERAL_AUTO_ALLOW", None)
+    return subprocess.run(
+        [sys.executable, str(SCRIPT_PATH)],
+        input=json.dumps(payload),
+        text=True,
+        capture_output=True,
+        check=False,
+        env=child_environment,
+        cwd=str(working_directory),
+    )
+
+
+def _write_settings_with_allow_list(fake_home: Path, allow_list: list[str]) -> None:
+    claude_directory = fake_home / ".claude"
+    claude_directory.mkdir(parents=True, exist_ok=True)
+    settings_payload = {"hooks": {"allowGitResetHardProjects": allow_list}}
+    (claude_directory / "settings.json").write_text(
+        json.dumps(settings_payload), encoding="utf-8"
+    )
+
+
+def test_git_reset_hard_allowed_when_cwd_matches_settings_allow_list(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "approved_project"
+    project_directory.mkdir()
+    project_path_forward = str(project_directory).replace("\\", "/")
+    _write_settings_with_allow_list(fake_home, [project_path_forward])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_asks_when_cwd_not_in_settings_allow_list(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    approved_directory = tmp_path / "approved_project"
+    approved_directory.mkdir()
+    unapproved_directory = tmp_path / "unapproved_project"
+    unapproved_directory.mkdir()
+    approved_path_forward = str(approved_directory).replace("\\", "/")
+    _write_settings_with_allow_list(fake_home, [approved_path_forward])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, unapproved_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+    assert "git reset --hard" in response["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_git_reset_hard_asks_when_settings_missing(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "unapproved_project"
+    project_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_asks_when_allow_list_is_empty(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    project_directory = tmp_path / "some_project"
+    project_directory.mkdir()
+    _write_settings_with_allow_list(fake_home, [])
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_allowed_in_linked_git_worktree(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    main_repository = tmp_path / "main_repository"
+    main_repository.mkdir()
+    subprocess.run(["git", "init", "-q"], cwd=main_repository, check=True)
+    subprocess.run(["git", "commit", "-q", "--allow-empty", "-m", "init"], cwd=main_repository, check=True)
+    worktree_directory = tmp_path / "worktree_copy"
+    subprocess.run(
+        ["git", "worktree", "add", "-q", "-b", "feature", str(worktree_directory)],
+        cwd=main_repository,
+        check=True,
+    )
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, worktree_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_allowed_when_path_contains_worktrees_segment(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    worktree_directory = tmp_path / "worktrees" / "some_feature"
+    worktree_directory.mkdir(parents=True)
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, worktree_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_allowed_under_os_temp_directory() -> None:
+    fake_home = Path(tempfile.mkdtemp(prefix="home_"))
+    working_directory = Path(tempfile.mkdtemp(prefix="ephemeral_work_"))
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, working_directory, disable_ephemeral_auto_allow=False)
+
+    assert result.stdout.strip() == ""
+    assert result.returncode == 0
+
+
+def test_git_reset_hard_asks_in_plain_directory_with_no_settings(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    plain_directory = tmp_path / "regular_project"
+    plain_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, plain_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"
+
+
+def test_git_reset_hard_asks_when_settings_file_is_invalid_json(tmp_path: Path) -> None:
+    fake_home = tmp_path / "home"
+    (fake_home / ".claude").mkdir(parents=True)
+    (fake_home / ".claude" / "settings.json").write_text(
+        "{not valid json", encoding="utf-8"
+    )
+    project_directory = tmp_path / "unapproved_project"
+    project_directory.mkdir()
+    payload = _make_bash_payload("git reset --hard origin/main")
+
+    result = _run_hook_with_fake_home(payload, fake_home, project_directory)
+
+    response = json.loads(result.stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "ask"

package/hooks/blocking/test_tdd_enforcer.py

@@ -96,7 +96,7 @@ def test_should_deny_when_test_file_exists_but_is_stale(tmp_path: Path) -> None:
     assert _decision_from(completed) == "deny"
 
 
-def test_should_allow_when_bypass_sentinel_present_in_content(tmp_path: Path) -> None:
+def test_should_deny_when_pragma_no_tdd_gate_sentinel_is_present_without_test(tmp_path: Path) -> None:
     sandbox = _sandbox(tmp_path)
     production_file = sandbox / "orders.py"
     content_with_sentinel = "# pragma: no-tdd-gate\ndef fulfill(): pass\n"
@@ -105,7 +105,7 @@ def test_should_allow_when_bypass_sentinel_present_in_content(tmp_path: Path) ->
         _make_write_payload(production_file, content_with_sentinel)
     )
 
-    assert _decision_from(completed) == "allow"
+    assert _decision_from(completed) == "deny"
 
 
 def test_should_skip_markdown_files_entirely(tmp_path: Path) -> None:
@@ -170,11 +170,12 @@ def test_should_deny_when_test_file_has_no_test_evidence(tmp_path: Path) -> None
     assert _decision_from(completed) == "deny"
 
 
-def test_should_allow_edit_when_bypass_sentinel_present_in_new_string(
+def test_should_deny_edit_when_pragma_sentinel_present_in_new_string_without_test(
     tmp_path: Path,
 ) -> None:
     sandbox = _sandbox(tmp_path)
     production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
     payload = {
         "tool_name": "Edit",
         "tool_input": {
@@ -186,9 +187,131 @@ def test_should_allow_edit_when_bypass_sentinel_present_in_new_string(
 
     completed = _run_hook_with_payload(payload)
 
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_python_file_with_only_module_level_constants(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_only_content = (
+        '"""Module-level constants for the widget subsystem."""\n'
+        "import re\n"
+        "MAXIMUM_RETRIES: int = 3\n"
+        "DEFAULT_TIMEOUT_SECONDS: float = 30.0\n"
+        'BANNED_WORDS: tuple[str, ...] = ("foo", "bar")\n'
+    )
+    constants_file.write_text(constants_only_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(constants_file, constants_only_content)
+    )
+
+    assert _decision_from(completed) == "allow"
+
+
+def test_should_deny_python_file_when_any_function_definition_is_present(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    mixed_file = sandbox / "mixed.py"
+    mixed_content = (
+        "MAXIMUM_RETRIES: int = 3\n"
+        "def do_something() -> None:\n"
+        "    return None\n"
+    )
+    mixed_file.write_text(mixed_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(mixed_file, mixed_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_deny_python_file_when_any_class_definition_is_present(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    class_file = sandbox / "klass.py"
+    class_content = (
+        "class Widget:\n"
+        "    size: int = 3\n"
+    )
+    class_file.write_text(class_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(class_file, class_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_deny_response_places_system_message_and_suppress_output_at_top_level(
+    tmp_path: Path,
+) -> None:
+    sandbox = _sandbox(tmp_path)
+    production_file = sandbox / "orders.py"
+    production_file.write_text("def fulfill(): pass\n")
+
+    completed = _run_hook_with_payload(_make_write_payload(production_file))
+
+    parsed = json.loads(completed.stdout)
+    hook_output = parsed["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert parsed.get("suppressOutput") is True
+    assert isinstance(parsed.get("systemMessage"), str)
+    assert parsed["systemMessage"]
+    assert "suppressOutput" not in hook_output
+    assert "systemMessage" not in hook_output
+    verbose_reason = hook_output["permissionDecisionReason"]
+    assert "propose" in verbose_reason.lower() or "enhancement" in verbose_reason.lower()
+
+
+def test_should_deny_python_file_that_calls_function_at_module_level(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    side_effect_file = sandbox / "side_effects.py"
+    side_effect_content = (
+        "import sys\n"
+        "sys.exit(1)\n"
+    )
+    side_effect_file.write_text(side_effect_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(side_effect_file, side_effect_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
+def test_should_allow_python_file_with_module_docstring_plus_constants(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    constants_file = sandbox / "constants.py"
+    constants_content = (
+        '"""Module-level constants for the widget subsystem."""\n'
+        "import re\n"
+        "MAXIMUM_RETRIES: int = 3\n"
+    )
+    constants_file.write_text(constants_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(constants_file, constants_content)
+    )
+
     assert _decision_from(completed) == "allow"
 
 
+def test_should_deny_python_file_that_mutates_module_state_via_aug_assign(tmp_path: Path) -> None:
+    sandbox = _sandbox(tmp_path)
+    mutation_file = sandbox / "mutation.py"
+    mutation_content = (
+        "COUNTER: int = 0\n"
+        "COUNTER += 1\n"
+    )
+    mutation_file.write_text(mutation_content)
+
+    completed = _run_hook_with_payload(
+        _make_write_payload(mutation_file, mutation_content)
+    )
+
+    assert _decision_from(completed) == "deny"
+
+
 def test_should_deny_production_file_inside_directory_containing_skip_substring(
     tmp_path: Path,
 ) -> None:

package/hooks/config/messages.py

@@ -1,4 +1,4 @@
-# pragma: no-tdd-gate
 """User-facing notice messages for blocking hooks."""
 
 USER_FACING_NOTICE = "Agent was found guessing - sourcing opinions..."
+USER_FACING_TDD_NOTICE = "TDD gate held - writing the failing test first..."

package/hooks/config/test_messages.py

@@ -0,0 +1,13 @@
+"""Smoke tests for hooks.config.messages — verify user-facing notice constants exist."""
+
+from config import messages
+
+
+def test_user_facing_notice_is_nonempty_string() -> None:
+    assert isinstance(messages.USER_FACING_NOTICE, str)
+    assert messages.USER_FACING_NOTICE
+
+
+def test_user_facing_tdd_notice_is_nonempty_string() -> None:
+    assert isinstance(messages.USER_FACING_TDD_NOTICE, str)
+    assert messages.USER_FACING_TDD_NOTICE

package/hooks/git-hooks/config.py

@@ -0,0 +1,48 @@
+"""Constants for the claude-dev-env git-hook entry points.
+
+Co-located with ``pre_commit.py`` and ``pre_push.py`` so the installed shim
+directory is self-contained at runtime: the shim prepends its own directory
+to ``sys.path`` before importing the hook module, which makes ``from config
+import ...`` resolve against this file both inside the repo and under
+``~/.claude/hooks/git-hooks/`` after installation.
+"""
+
+from __future__ import annotations
+
+
+STAGED_SCOPE_ARGUMENT: str = "--staged"
+BASE_REFERENCE_ARGUMENT: str = "--base"
+DEFAULT_REMOTE_BASE_REFERENCE: str = "origin/HEAD"
+ALL_ZEROS_OBJECT_NAME_CHARACTER: str = "0"
+STDIN_LINE_FIELD_COUNT: int = 4
+STDIN_REMOTE_OBJECT_FIELD_INDEX: int = 3
+GATE_PATH_OVERRIDE_ENV_VAR: str = "CODE_RULES_GATE_PATH"
+CLAUDE_HOME_ENV_VAR: str = "CLAUDE_HOME"
+CLAUDE_HOME_DEFAULT_SUBDIRECTORY: str = ".claude"
+GATE_SCRIPT_RELATIVE_PATH: tuple[str, ...] = (
+    "skills",
+    "bugteam",
+    "scripts",
+    "bugteam_code_rules_gate.py",
+)
+GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE: int = 2
+GATE_SCRIPT_NOT_FOUND_MESSAGE: str = (
+    "claude-dev-env pre-commit: gate script not found at {path}, skipping enforcement"
+)
+PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE: str = (
+    "claude-dev-env pre-push: gate script not found at {path}, skipping enforcement"
+)
+STDIN_READ_FAILURE_MESSAGE: str = (
+    "claude-dev-env pre-push: could not read stdin ({error}), aborting"
+)
+INVOKE_GATE_FAILURE_MESSAGE: str = (
+    "claude-dev-env: could not launch gate script ({error}), aborting"
+)
+MALFORMED_STDIN_LINE_MESSAGE: str = (
+    "claude-dev-env pre-push: ignoring malformed stdin line: {line!r}"
+)
+LOCAL_SHA_FIELD_INDEX: int = 1
+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__"

package/hooks/git-hooks/gate_utils.py

@@ -0,0 +1,86 @@
+"""Shared utilities for the claude-dev-env git-hook entry points."""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+from config import (
+    CLAUDE_HOME_DEFAULT_SUBDIRECTORY,
+    CLAUDE_HOME_ENV_VAR,
+    GATE_PATH_OVERRIDE_ENV_VAR,
+    GATE_SCRIPT_RELATIVE_PATH,
+)
+
+
+def resolve_gate_script_path() -> tuple[Path, Path | None]:
+    """Return (gate_path, exact_allowed_override_or_none).
+
+    When CODE_RULES_GATE_PATH is set the second element is the resolved
+    override path — the only path is_safe_regular_file will accept.
+    When falling back to CLAUDE_HOME / default the second element is None,
+    signalling that the trusted prefix (Path.home() / '.claude') applies.
+
+    Capturing both values here eliminates the TOCTOU window that would arise
+    when the same env vars are read again inside is_safe_regular_file.
+    """
+    override_path_raw = os.environ.get(GATE_PATH_OVERRIDE_ENV_VAR, "").strip()
+    if override_path_raw:
+        exact_override = Path(override_path_raw).resolve()
+        return exact_override, exact_override
+    claude_home_override = os.environ.get(CLAUDE_HOME_ENV_VAR, "").strip()
+    if claude_home_override:
+        claude_home_directory = Path(claude_home_override).resolve()
+    else:
+        claude_home_directory = Path.home() / CLAUDE_HOME_DEFAULT_SUBDIRECTORY
+    gate_path = claude_home_directory.joinpath(*GATE_SCRIPT_RELATIVE_PATH)
+    return gate_path, None
+
+
+def is_safe_regular_file(candidate_path: Path, exact_allowed_path: Path | None) -> bool:
+    """Return True only when candidate_path is a regular file at a trusted location.
+
+    When exact_allowed_path is not None candidate_path must resolve to that
+    exact path (CODE_RULES_GATE_PATH override case).  When it is None the
+    resolved candidate must fall within Path.home() / '.claude' — CLAUDE_HOME
+    is intentionally excluded from the trust boundary because it is
+    attacker-settable via the process environment.
+
+    The candidate is resolved to its real path before any containment check,
+    preventing symlinks inside the trusted tree from redirecting execution
+    outside it.
+    """
+    resolved_candidate = candidate_path.resolve()
+    if not _is_resolved_candidate_allowed(resolved_candidate, exact_allowed_path):
+        return False
+    try:
+        path_stat = os.stat(resolved_candidate)
+    except OSError:
+        return False
+    return stat.S_ISREG(path_stat.st_mode)
+
+
+def _resolve_trust_root() -> Path:
+    claude_home_override = os.environ.get(CLAUDE_HOME_ENV_VAR, "").strip()
+    if claude_home_override:
+        return Path(claude_home_override).resolve()
+    return (Path.home() / CLAUDE_HOME_DEFAULT_SUBDIRECTORY).resolve()
+
+
+def _is_resolved_candidate_allowed(
+    resolved_candidate: Path,
+    exact_allowed_path: Path | None,
+) -> bool:
+    if exact_allowed_path is not None:
+        return resolved_candidate == exact_allowed_path
+    trusted_prefix = _resolve_trust_root()
+    return _is_within_directory(resolved_candidate, trusted_prefix)
+
+
+def _is_within_directory(candidate_path: Path, directory: Path) -> bool:
+    try:
+        candidate_path.relative_to(directory)
+        return True
+    except ValueError:
+        return False

package/hooks/git-hooks/pre_commit.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Git pre-commit hook: run the CODE_RULES gate over staged changes.
+
+Installed to the user's shared git-hooks directory via the claude-dev-env
+installer; git invokes this file as `pre-commit` (the installer strips the
+`_` and `.py` suffix when copying into the live hooks path).
+
+Exit codes:
+  0 - staged changes pass the gate (or the gate is not installed locally).
+  1 - staged changes introduce one or more blocking violations.
+  2 - unexpected invocation failure (e.g., subprocess could not launch).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+from config import (
+    GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
+    GATE_SCRIPT_NOT_FOUND_MESSAGE,
+    INVOKE_GATE_FAILURE_MESSAGE,
+    STAGED_SCOPE_ARGUMENT,
+)
+from gate_utils import is_safe_regular_file, resolve_gate_script_path
+
+
+def invoke_gate(gate_script_path: Path) -> int:
+    staged_scope_argument = STAGED_SCOPE_ARGUMENT
+    invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
+    gate_infrastructure_failure_exit_code = GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
+    try:
+        resolved_gate_path = gate_script_path.resolve(strict=True)
+        completion = subprocess.run(
+            [sys.executable, str(resolved_gate_path), staged_scope_argument],
+            check=False,
+        )
+    except OSError as launch_error:
+        print(
+            invoke_gate_failure_message.format(error=launch_error),
+            file=sys.stderr,
+        )
+        return gate_infrastructure_failure_exit_code
+    return completion.returncode
+
+
+def main() -> int:
+    gate_script_not_found_message = GATE_SCRIPT_NOT_FOUND_MESSAGE
+    gate_script_path, exact_allowed_path = resolve_gate_script_path()
+    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
+        print(
+            gate_script_not_found_message.format(path=gate_script_path),
+            file=sys.stderr,
+        )
+        return 0
+    return invoke_gate(gate_script_path)
+
+
+if __name__ == "__main__":
+    sys.exit(main())