claude-dev-env 2.3.0 → 2.5.0

package/hooks/blocking/code_review_pr_create_gate.py

@@ -0,0 +1,198 @@
+"""PreToolUse gate: PR create lands only behind a clean xhigh code-review stamp.
+
+Fires when ``CODE_REVIEW_ENFORCEMENT_ENABLED`` is on (default off). Runs on
+Bash/PowerShell ``gh pr create`` and on the MCP ``create_pull_request``
+tool. Resolves the repository from the session
+working directory (or the payload cwd), computes the live change-surface
+hash, and allows the create only when a clean stamp at effort ``xhigh`` or
+higher covers that exact hash under ``~/.claude/code-review-stamps/``.
+
+Empty surfaces and repos with no resolvable upstream base are out of scope
+and allowed. Push lands behind ``code_review_push_gate`` and commit behind
+``verified_commit_gate``; this gate covers pull-request creation only.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+
+    register_code_review_enforcement_constants()
+    register_verified_commit_constants()
+
+    from code_review_gate_deny import (
+        build_code_review_deny_payload,
+        log_and_emit_code_review_deny,
+    )
+    from code_review_stamp_store import live_surface_hash, stamp_covers_surface
+    from config.code_review_enforcement_constants import (
+        ALL_GATED_SHELL_TOOL_NAMES,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
+        GH_PR_CREATE_INVOCATION_PATTERN,
+        HASH_PREVIEW_LENGTH,
+        MCP_CREATE_PULL_REQUEST_TOOL_NAME,
+        PR_CREATE_GATE_CORRECTIVE_MESSAGE,
+        PR_CREATE_GATE_HOOK_MODULE_NAME,
+        PR_CREATE_REQUIRED_EFFORT,
+    )
+    from verification_verdict_store import resolve_repo_root
+except ImportError as import_error:
+    raise ImportError(
+        "the code_review_pr_create_gate dependencies did not import; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _strip_quoted_regions(command_text: str) -> str:
+    """Blank out single- and double-quoted spans so prose is not gated."""
+    quote_pattern = re.compile(r"\"[^\"]*\"|'[^']*'")
+    return quote_pattern.sub(lambda each_match: " " * len(each_match.group(0)), command_text)
+
+
+def command_invokes_gh_pr_create(command_text: str) -> bool:
+    """Decide whether a shell command invokes ``gh pr create``.
+
+    ::
+
+        gh pr create --title T --body-file b.md  -> True
+        echo "gh pr create"                      -> False (quoted prose)
+        gh pr edit 1 --title T                   -> False
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        True when the command contains a real ``gh pr create`` invocation.
+    """
+    quote_stripped_command = _strip_quoted_regions(command_text)
+    invocation_pattern = re.compile(GH_PR_CREATE_INVOCATION_PATTERN, re.IGNORECASE)
+    return invocation_pattern.search(quote_stripped_command) is not None
+
+
+def is_mcp_create_pull_request_tool(tool_name: str) -> bool:
+    """Decide whether a tool name is the MCP create-pull-request tool.
+
+    Args:
+        tool_name: The PreToolUse ``tool_name`` field.
+
+    Returns:
+        True when the name is the configured MCP create-PR tool.
+    """
+    return tool_name == MCP_CREATE_PULL_REQUEST_TOOL_NAME
+
+
+def deny_reason_for_directory(target_directory: str) -> str | None:
+    """Decide whether a PR create from a directory must be blocked.
+
+    ::
+
+        enforcement off / no repo / empty surface / covering xhigh stamp -> None
+        production surface without xhigh-or-higher stamp -> corrective (deny)
+
+    Args:
+        target_directory: The session or repo directory the create targets.
+
+    Returns:
+        The deny reason when the surface needs a clean xhigh stamp and none
+        covers it; None when the create may proceed.
+    """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
+    repo_root = resolve_repo_root(target_directory)
+    if repo_root is None:
+        return None
+    surface_hash = live_surface_hash(repo_root)
+    if surface_hash is None:
+        return None
+    if stamp_covers_surface(repo_root, surface_hash, PR_CREATE_REQUIRED_EFFORT):
+        return None
+    hash_preview = surface_hash[:HASH_PREVIEW_LENGTH]
+    return (
+        f"{PR_CREATE_GATE_CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"
+    )
+
+
+def _deny_for_directory_or_none(
+    session_directory: str,
+) -> dict[str, dict[str, str]] | None:
+    """Return the deny payload for a directory that lacks a covering stamp."""
+    deny_reason = deny_reason_for_directory(session_directory)
+    if deny_reason is None:
+        return None
+    return build_code_review_deny_payload(deny_reason)
+
+
+def _shell_command_targets_pr_create(all_pretooluse_payload: dict[str, object]) -> bool:
+    """Decide whether a shell payload carries a real ``gh pr create``."""
+    tool_input = all_pretooluse_payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return False
+    command_text = tool_input.get("command", "")
+    if not isinstance(command_text, str) or not command_text:
+        return False
+    return command_invokes_gh_pr_create(command_text)
+
+
+def decision_for_payload(
+    all_pretooluse_payload: dict[str, object],
+) -> dict[str, dict[str, str]] | None:
+    """Build the deny decision for a gated PR-create attempt.
+
+    Args:
+        all_pretooluse_payload: The PreToolUse hook payload.
+
+    Returns:
+        The deny decision mapping when the create lacks a covering xhigh
+        stamp; None when the create may proceed.
+    """
+    tool_name = all_pretooluse_payload.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        return None
+    session_directory = all_pretooluse_payload.get("cwd", ".")
+    if not isinstance(session_directory, str):
+        session_directory = "."
+    if is_mcp_create_pull_request_tool(tool_name):
+        return _deny_for_directory_or_none(session_directory)
+    if tool_name not in ALL_GATED_SHELL_TOOL_NAMES:
+        return None
+    if not _shell_command_targets_pr_create(all_pretooluse_payload):
+        return None
+    return _deny_for_directory_or_none(session_directory)
+
+
+def main() -> None:
+    """Read the PreToolUse payload and decide whether to allow the PR create."""
+    try:
+        pretooluse_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    deny_decision = decision_for_payload(pretooluse_payload)
+    if deny_decision is None:
+        return
+    tool_name = pretooluse_payload.get("tool_name", "")
+    deny_reason = deny_decision["hookSpecificOutput"]["permissionDecisionReason"]
+    if not isinstance(deny_reason, str):
+        return
+    log_and_emit_code_review_deny(
+        deny_reason,
+        tool_name if isinstance(tool_name, str) else "",
+        PR_CREATE_GATE_HOOK_MODULE_NAME,
+    )
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/code_review_push_gate.py

@@ -0,0 +1,145 @@
+"""PreToolUse gate: git push lands only behind a clean low code-review stamp.
+
+Fires on Bash/PowerShell tool calls when ``CODE_REVIEW_ENFORCEMENT_ENABLED``
+is on (default off). When the command carries a ``git push``, the gate
+resolves each repository the push targets, computes the live
+change-surface hash against the merge base, and allows the push only when a
+clean stamp at effort ``low`` or higher covers that exact hash under
+``~/.claude/code-review-stamps/``.
+
+Allowed without a stamp:
+
+- a command carrying the bypass marker (``# code-review-skip``) as a trailing
+  shell comment,
+- a repository with no resolvable upstream base,
+- a mechanically exempt surface (docs and image files, pytest test files, and
+  Python files whose docstring-stripped AST is unchanged), and
+- a surface a clean ``low``-or-higher stamp already covers.
+
+Commit lands behind ``verified_commit_gate``; only push is gated here.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+
+    register_code_review_enforcement_constants()
+    register_verified_commit_constants()
+
+    from code_review_gate_deny import log_and_emit_code_review_deny
+    from code_review_stamp_store import live_surface_hash, stamp_covers_surface
+    from config.code_review_enforcement_constants import (
+        ALL_GATED_SHELL_TOOL_NAMES,
+        CODE_REVIEW_BYPASS_MARKER,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
+        GATED_PUSH_SUBCOMMANDS,
+        HASH_PREVIEW_LENGTH,
+        PUSH_GATE_CORRECTIVE_MESSAGE,
+        PUSH_GATE_HOOK_MODULE_NAME,
+        PUSH_REQUIRED_EFFORT,
+    )
+    from verification_verdict_store import (
+        is_verification_exempt_diff,
+        resolve_merge_base,
+        resolve_repo_root,
+    )
+    from verified_commit_gate_parts.command_tokenization import (
+        command_carries_trailing_marker,
+    )
+    from verified_commit_gate_parts.gated_invocations import gated_repo_directories
+except ImportError as import_error:
+    raise ImportError(
+        "the code_review_push_gate dependencies did not import; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def deny_reason_for_directory(target_directory: str) -> str | None:
+    """Decide whether a push from a directory must be blocked.
+
+    Allowed when enforcement is off, the directory is no repo, has no upstream
+    base, is a mechanically exempt surface, or a clean low-or-higher stamp
+    covers it.
+
+    Args:
+        target_directory: The directory the push targets.
+
+    Returns:
+        The deny reason when the surface lacks a covering low stamp, else None.
+    """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
+    repo_root = resolve_repo_root(target_directory)
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    if is_verification_exempt_diff(repo_root, merge_base_sha):
+        return None
+    surface_hash = live_surface_hash(repo_root)
+    if surface_hash is None:
+        return None
+    if stamp_covers_surface(repo_root, surface_hash, PUSH_REQUIRED_EFFORT):
+        return None
+    hash_preview = surface_hash[:HASH_PREVIEW_LENGTH]
+    return f"{PUSH_GATE_CORRECTIVE_MESSAGE} (repo: {repo_root}, surface sha256 {hash_preview}...)"
+
+
+def _emit_first_denied_directory(command_text: str, session_directory: str, tool_name: str) -> None:
+    """Deny the push against the first target directory that lacks a stamp."""
+    all_target_directories = gated_repo_directories(
+        command_text, session_directory, all_gated_subcommands=GATED_PUSH_SUBCOMMANDS
+    )
+    for each_target_directory in all_target_directories:
+        deny_reason = deny_reason_for_directory(each_target_directory)
+        if deny_reason is None:
+            continue
+        log_and_emit_code_review_deny(deny_reason, tool_name, PUSH_GATE_HOOK_MODULE_NAME)
+        return
+
+
+def main() -> None:
+    """Read the PreToolUse payload and decide whether to allow the push.
+
+    Allows the command without a stamp when it carries the bypass marker
+    (``CODE_REVIEW_BYPASS_MARKER``) as a genuine trailing shell comment;
+    otherwise denies a push whose surface lacks a covering low stamp.
+    """
+    try:
+        pretooluse_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    tool_name = pretooluse_payload.get("tool_name", "")
+    if tool_name not in ALL_GATED_SHELL_TOOL_NAMES:
+        return
+    tool_input = pretooluse_payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return
+    command_text = tool_input.get("command", "")
+    if not isinstance(command_text, str) or not command_text:
+        return
+    if command_carries_trailing_marker(command_text, CODE_REVIEW_BYPASS_MARKER):
+        return
+    session_directory = pretooluse_payload.get("cwd", ".")
+    if not isinstance(session_directory, str):
+        session_directory = "."
+    _emit_first_denied_directory(command_text, session_directory, tool_name)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/code_review_stamp_directory_write_blocker.py

@@ -0,0 +1,348 @@
+#!/usr/bin/env python3
+"""PreToolUse guard: deny shell and file-tool access to the stamp directory.
+
+Runs only when ``CODE_REVIEW_ENFORCEMENT_ENABLED`` is on (default off); with
+the flag off the guard allows every stamp-directory access.
+
+The push and PR-create gates trust a single invariant: only
+``invoke_code_review.py --record-stamp`` mints stamp files under
+``~/.claude/code-review-stamps/``. settings.json cannot be the only shipped
+protection, so this guard fires on both surfaces:
+
+- Bash / PowerShell: deny any command that names the stamp directory (absolute
+  path, cd-then-relative write, cd into the stamp directory, a split directory
+  change through the Claude home into the stamp directory, stamp-file shape, a
+  path-join write, or a path assembled by obfuscation that decodes to a stamp
+  segment), or that imports the stamp store module or calls its mint function.
+- Write / Edit / MultiEdit: deny any path under the stamp directory.
+
+No legitimate workflow reaches that directory through a shell or the file
+tools: the invoker writes in-process after a clean review, so the sanctioned
+minter command names none of these matchers and passes without an allowlist.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+try:
+    _blocking_directory = str(Path(__file__).resolve().parent)
+    if _blocking_directory not in sys.path:
+        sys.path.insert(0, _blocking_directory)
+    _hooks_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_directory not in sys.path:
+        sys.path.append(_hooks_directory)
+
+    from code_review_enforcement_config_bootstrap import (
+        register_code_review_enforcement_constants,
+    )
+    from verified_commit_config_bootstrap import register_verified_commit_constants
+
+    register_code_review_enforcement_constants()
+    register_verified_commit_constants()
+
+    from code_review_stamp_store import stamp_directory
+    from code_review_stamp_write_blocker_parts.obfuscated_stamp_path_reference import (
+        references_obfuscated_stamp_path,
+    )
+    from code_review_stamp_write_blocker_parts.split_directory_change_into_stamp import (
+        changes_through_split_directory_into_stamp,
+        directory_change_prefix,
+    )
+    from config.code_review_enforcement_constants import (
+        ALL_GATED_SHELL_TOOL_NAMES,
+        ALL_STAMP_STORE_FORGE_PATTERNS,
+        ALL_WRITE_EDIT_TOOL_NAMES,
+        CODE_REVIEW_ENFORCEMENT_ENABLED,
+        DENY_PERMISSION_DECISION,
+        PRE_TOOL_USE_HOOK_EVENT_NAME,
+        RELATIVE_STAMP_DIRECTORY_PATTERN,
+        STAMP_DIRECTORY_GUARD_MESSAGE,
+        STAMP_DIRECTORY_NAME,
+        STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN,
+        STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN,
+        STAMP_WRITE_BLOCKER_HOOK_MODULE_NAME,
+    )
+    from config.verified_commit_constants import (
+        CLAUDE_HOME_DIRECTORY_NAME,
+        CLAUDE_HOME_TARGET_BOUNDARY_PATTERN,
+        COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN,
+        DIRECTORY_CHANGE_TARGET_PATTERN,
+        NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN,
+        ROOT_KEY_HEX_LENGTH,
+        VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN,
+        VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN,
+        VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN,
+        VERDICT_PATH_GLUE_PATTERN,
+    )
+
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.pre_tool_use_stdin import (
+        read_hook_input_dictionary_from_stdin,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "code_review_stamp_directory_write_blocker: cannot import its dependencies; "
+        "ensure the blocking directory is importable."
+    ) from import_error
+
+
+def _stamp_file_relative_reference_pattern() -> str:
+    """Build the ``code-review-stamps/<root-key>.json`` stamp-file shape pattern."""
+    root_key_json_suffix = STAMP_FILE_ROOT_KEY_JSON_SUFFIX_PATTERN % ROOT_KEY_HEX_LENGTH
+    return (
+        f"{STAMP_FILE_REFERENCE_BOUNDARY_PREFIX_PATTERN}"
+        f"{re.escape(STAMP_DIRECTORY_NAME)}{root_key_json_suffix}"
+    )
+
+
+def _references_absolute_stamp_path(command_text: str) -> bool:
+    """Decide whether a command names an absolute stamp-directory path."""
+    stamp_directory_pattern = re.compile(
+        re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_NAME_SEPARATOR_PATTERN
+        + re.escape(STAMP_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_PATH_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    return stamp_directory_pattern.search(command_text) is not None
+
+
+def _changes_into_claude_home_then_writes_relative(command_text: str) -> bool:
+    """Decide whether a command enters the Claude home then writes the stamp dir."""
+    directory_change_into_claude_pattern = re.compile(
+        directory_change_prefix()
+        + DIRECTORY_CHANGE_TARGET_PATTERN
+        + re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + CLAUDE_HOME_TARGET_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    change_match = directory_change_into_claude_pattern.search(command_text)
+    if change_match is None:
+        return False
+    relative_stamp_pattern = re.compile(RELATIVE_STAMP_DIRECTORY_PATTERN, re.IGNORECASE)
+    return relative_stamp_pattern.search(command_text, change_match.end()) is not None
+
+
+def _changes_into_stamp_directory_then_writes(command_text: str) -> bool:
+    """Decide whether a command enters the stamp directory then runs a command."""
+    directory_change_into_stamp_pattern = re.compile(
+        directory_change_prefix()
+        + DIRECTORY_CHANGE_TARGET_PATTERN
+        + re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+        + r"[\\/]"
+        + re.escape(STAMP_DIRECTORY_NAME)
+        + VERDICT_DIRECTORY_TARGET_BOUNDARY_PATTERN,
+        re.IGNORECASE,
+    )
+    change_match = directory_change_into_stamp_pattern.search(command_text)
+    if change_match is None:
+        return False
+    command_after_change_pattern = re.compile(COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN)
+    return (
+        command_after_change_pattern.search(command_text, change_match.end())
+        is not None
+    )
+
+
+def _references_stamp_file_shape(command_text: str) -> bool:
+    """Decide whether a command names a stamp file's ``<root-key>.json`` shape."""
+    stamp_file_pattern = re.compile(
+        _stamp_file_relative_reference_pattern(), re.IGNORECASE
+    )
+    return stamp_file_pattern.search(command_text) is not None
+
+
+def _segments_join_as_stamp_path(command_text: str) -> bool:
+    """Decide whether the two name segments sit adjacent in a path-join shape."""
+    home_name = re.escape(CLAUDE_HOME_DIRECTORY_NAME)
+    stamp_name = re.escape(STAMP_DIRECTORY_NAME)
+    path_join_pattern = re.compile(
+        home_name
+        + VERDICT_PATH_GLUE_PATTERN
+        + stamp_name
+        + "|"
+        + stamp_name
+        + VERDICT_PATH_GLUE_PATTERN
+        + home_name,
+        re.IGNORECASE,
+    )
+    return path_join_pattern.search(command_text) is not None
+
+
+def _writes_with_stamp_path_intent(command_text: str) -> bool:
+    """Decide whether a write joins the two name segments into a stamp path."""
+    has_non_redirect_write = (
+        re.search(NON_REDIRECT_FILE_WRITE_PRIMITIVE_PATTERN, command_text) is not None
+    )
+    if not has_non_redirect_write:
+        return False
+    return _segments_join_as_stamp_path(command_text)
+
+
+def _references_store_module_or_mint_call(command_text: str) -> bool:
+    """Decide whether a command imports the stamp store or calls its mint call.
+
+    ::
+
+        python -c "from code_review_stamp_store import record_clean_stamp"  -> True
+        python -c "record_clean_stamp(root, live_hash, 'xhigh')"            -> True
+        python -m pytest test_code_review_stamp_store.py                    -> False
+
+    A forge that re-implements the mint in-process names no stamp path, so the
+    path matchers miss it. Matching the store import and the mint call closes
+    that gap. A pytest run naming the store test file matches none of these.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        True when the command imports ``code_review_stamp_store`` or calls
+        ``record_clean_stamp``; False otherwise.
+    """
+    for each_forge_pattern in ALL_STAMP_STORE_FORGE_PATTERNS:
+        if re.search(each_forge_pattern, command_text):
+            return True
+    return False
+
+
+def references_stamp_directory(command_text: str) -> bool:
+    """Decide whether a command references the code-review stamp directory.
+
+    Args:
+        command_text: The raw command string from the tool payload.
+
+    Returns:
+        True when the command names the stamp directory through any matcher — a
+        store import or mint call, an absolute path, a cd-then-relative write, a
+        cd into the directory, a split directory change into the directory, a
+        stamp-file shape, a path-join write, or an obfuscation-decoded stamp
+        segment; False otherwise.
+    """
+    if _references_store_module_or_mint_call(command_text):
+        return True
+    if _references_absolute_stamp_path(command_text):
+        return True
+    if _changes_into_claude_home_then_writes_relative(command_text):
+        return True
+    if _changes_into_stamp_directory_then_writes(command_text):
+        return True
+    if changes_through_split_directory_into_stamp(command_text):
+        return True
+    if _references_stamp_file_shape(command_text):
+        return True
+    if _writes_with_stamp_path_intent(command_text):
+        return True
+    return references_obfuscated_stamp_path(command_text)
+
+
+def path_targets_stamp_directory(file_path: str) -> bool:
+    """Decide whether a Write/Edit/MultiEdit path sits under the stamp directory.
+
+    Args:
+        file_path: The path the file tool targets.
+
+    Returns:
+        True when the resolved path is under ``~/.claude/code-review-stamps/``.
+    """
+    if not file_path:
+        return False
+    try:
+        resolved_target = Path(file_path).expanduser().resolve()
+        resolved_stamp_root = stamp_directory().resolve()
+    except OSError:
+        return False
+    if resolved_target == resolved_stamp_root:
+        return True
+    try:
+        resolved_target.relative_to(resolved_stamp_root)
+    except ValueError:
+        return False
+    return True
+
+
+def build_deny_payload() -> dict[str, dict[str, str]]:
+    """Build the PreToolUse deny payload for a stamp-directory access."""
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": PRE_TOOL_USE_HOOK_EVENT_NAME,
+            "permissionDecision": DENY_PERMISSION_DECISION,
+            "permissionDecisionReason": STAMP_DIRECTORY_GUARD_MESSAGE,
+        }
+    }
+
+
+def _shell_decision(all_tool_input: dict[str, object]) -> dict[str, dict[str, str]] | None:
+    """Return the deny payload when a shell command targets the stamp directory."""
+    command_text = all_tool_input.get("command", "")
+    if not isinstance(command_text, str) or not command_text:
+        return None
+    if not references_stamp_directory(command_text):
+        return None
+    return build_deny_payload()
+
+
+def _file_decision(all_tool_input: dict[str, object]) -> dict[str, dict[str, str]] | None:
+    """Return the deny payload when a file-tool path targets the stamp directory."""
+    file_path = all_tool_input.get("file_path", "")
+    if not isinstance(file_path, str):
+        return None
+    if not path_targets_stamp_directory(file_path):
+        return None
+    return build_deny_payload()
+
+
+def decision_for_payload(
+    all_pretooluse_payload: dict[str, object],
+) -> dict[str, dict[str, str]] | None:
+    """Build the deny decision for stamp-directory shell or file-tool access.
+
+    Returns None immediately when `CODE_REVIEW_ENFORCEMENT_ENABLED` is off.
+
+    Args:
+        all_pretooluse_payload: The PreToolUse hook payload.
+
+    Returns:
+        The deny decision mapping when a gated tool targets the stamp
+        directory; None when the tool call may proceed.
+    """
+    if not CODE_REVIEW_ENFORCEMENT_ENABLED:
+        return None
+    tool_name = all_pretooluse_payload.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        return None
+    tool_input = all_pretooluse_payload.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        return None
+    if tool_name in ALL_GATED_SHELL_TOOL_NAMES:
+        return _shell_decision(tool_input)
+    if tool_name not in ALL_WRITE_EDIT_TOOL_NAMES:
+        return None
+    return _file_decision(tool_input)
+
+
+def main() -> None:
+    """Read the PreToolUse payload and deny stamp-directory access."""
+    pretooluse_payload = read_hook_input_dictionary_from_stdin()
+    if pretooluse_payload is None:
+        return
+    deny_decision = decision_for_payload(pretooluse_payload)
+    if deny_decision is None:
+        return
+    raw_tool_name = pretooluse_payload.get("tool_name", "")
+    tool_name_for_log = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    log_hook_block(
+        calling_hook_name=STAMP_WRITE_BLOCKER_HOOK_MODULE_NAME,
+        hook_event=PRE_TOOL_USE_HOOK_EVENT_NAME,
+        block_reason=STAMP_DIRECTORY_GUARD_MESSAGE,
+        tool_name=tool_name_for_log,
+    )
+    sys.stdout.write(json.dumps(deny_decision) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()