claude-dev-env 8.102.0 → 8.103.0

package/hooks/blocking/turn_review_gate.py

@@ -0,0 +1,362 @@
+#!/usr/bin/env python3
+"""Stop hook that has a fresh reviewer read each turn's changes before the turn ends.
+
+The agent edits ``src/service.py`` and drops a retry. When the turn stops, a
+separate ``claude -p`` run reviews only that turn's edits with
+``/code-review low`` and the hook holds the stop with what it found::
+
+    prompt arrives  ->  snapshot A of the working tree
+    agent edits     ->  src/service.py loses @with_retry
+    stop            ->  snapshot B (parent A), claude -p "/code-review low A..B"
+                    ->  block: "src/service.py:208 - The diff removes ..."
+    agent fixes it  ->  stop reviews B..C only, finds nothing, the turn ends
+
+``turn_review_snapshot`` builds the snapshots, and ``turn_review_findings``
+reads the findings out of the review text. Edits the user left before the
+prompt sit in snapshot A, so the review sees only the agent's work. Each stop
+moves the baseline to the snapshot it took, so the stop after a block reviews
+only the fix.
+
+A repository takes part when it is the session's project folder or a folder
+directly inside it, and its GitHub origin ``owner/repo`` slug is listed in
+``CLAUDE_TURN_REVIEW_REPOSITORIES``. The hook holds a stop at most three times
+in a row, skips a turn that changed more than 30 files, and lets the stop
+through when the review fails or times out; a new prompt resets the count.
+These are the limits of Anthropic's security-guidance plugin. The review run
+carries ``CLAUDE_TURN_REVIEW_CHILD=1`` and none of the parent session's id,
+messaging or ingress variables, and the hook does nothing inside such a run. The review may read
+files and run ``git diff``, ``git show`` and ``git log``; every other tool is
+denied.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from atomic_file_writer import write_text_atomically
+from hooks_constants.atomic_file_writer_constants import ATOMIC_WRITE_TEMPORARY_SUFFIX
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.session_file_id import session_file_id
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+from hooks_constants.turn_review_gate_constants import (
+    ALL_PARENT_SESSION_VARIABLES,
+    ALL_REVIEW_ALLOWED_TOOLS,
+    ALL_REVIEW_DISALLOWED_TOOLS,
+    BASELINE_COMMIT_PATTERN,
+    BLOCK_DECISION,
+    BLOCK_REASON_TEMPLATE,
+    DECISION_KEY,
+    FINDING_LINE_SEPARATOR,
+    GIT_DIRECTORY_NAME,
+    HOOK_EVENT_NAME_KEY,
+    MAXIMUM_BLOCKS_IN_A_ROW,
+    MAXIMUM_TURN_FILES,
+    PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE,
+    PROMPT_EVENT_NAME,
+    REASON_KEY,
+    REPOSITORIES_ENVIRONMENT_VARIABLE,
+    REPOSITORY_FINDINGS_SEPARATOR,
+    REPOSITORY_FINDINGS_TEMPLATE,
+    REPOSITORY_SEPARATOR,
+    REVIEW_CHILD_ENVIRONMENT_VARIABLE,
+    REVIEW_CHILD_MARKER,
+    REVIEW_EFFORT,
+    REVIEW_FAILURE_DIAGNOSTIC_TEMPLATE,
+    REVIEW_MODEL_ALIAS,
+    REVIEW_PROMPT_TEMPLATE,
+    REVIEW_RESULT_KEY,
+    REVIEW_EXECUTABLE_NAME,
+    REVIEW_SETTING_SOURCES_TEXT,
+    REVIEW_SETTINGS_TEXT,
+    MINIMUM_REVIEW_SECONDS,
+    REVIEW_TIMEOUT_SECONDS,
+    REVIEW_TOOLS_TEXT,
+    SESSION_ID_KEY,
+    STATE_BASELINES_KEY,
+    STATE_BLOCKS_KEY,
+    STATE_FILE_TEMPLATE,
+    STATE_TEMPORARY_PREFIX,
+    STATE_TEXT_ENCODING,
+    STOP_EVENT_NAME,
+    TOO_MANY_FILES_DIAGNOSTIC_TEMPLATE,
+)
+from pii_prevention_blocker_parts.repository_exemption import repository_origin_slug
+from turn_review_findings import finding_lines
+from turn_review_snapshot import turn_changed_paths, working_tree_snapshot
+
+
+def _opted_in_repository_slugs() -> frozenset[str]:
+    listed = os.environ.get(REPOSITORIES_ENVIRONMENT_VARIABLE, "")
+    return frozenset(
+        each.strip().casefold() for each in listed.split(REPOSITORY_SEPARATOR) if each.strip()
+    )
+
+
+def _opted_in_repository_roots(all_slugs: frozenset[str]) -> list[Path]:
+    project_directory = os.environ.get(PROJECT_DIRECTORY_ENVIRONMENT_VARIABLE, "")
+    if not project_directory or not Path(project_directory).is_dir():
+        return []
+    project_path = Path(project_directory).resolve()
+    all_candidates = [project_path, *sorted(_child_entries(project_path))]
+    return [each for each in all_candidates if _is_opted_in_checkout(each, all_slugs)]
+
+
+def _child_entries(project_path: Path) -> list[Path]:
+    try:
+        return list(project_path.iterdir())
+    except OSError:
+        return []
+
+
+def _is_opted_in_checkout(folder: Path, all_slugs: frozenset[str]) -> bool:
+    try:
+        is_checkout = folder.is_dir() and (folder / GIT_DIRECTORY_NAME).exists()
+    except OSError:
+        return False
+    return is_checkout and repository_origin_slug(folder) in all_slugs
+
+
+def _review_command(base_commit: str, turn_commit: str) -> list[str]:
+    review_prompt = REVIEW_PROMPT_TEMPLATE.format(
+        effort=REVIEW_EFFORT, base_commit=base_commit, turn_commit=turn_commit
+    )
+    return [
+        shutil.which(REVIEW_EXECUTABLE_NAME) or REVIEW_EXECUTABLE_NAME,
+        "-p",
+        review_prompt,
+        "--model",
+        REVIEW_MODEL_ALIAS,
+        "--output-format",
+        "json",
+        "--permission-mode",
+        "dontAsk",
+        "--setting-sources",
+        REVIEW_SETTING_SOURCES_TEXT,
+        "--tools",
+        REVIEW_TOOLS_TEXT,
+        "--no-session-persistence",
+        "--allowedTools",
+        *ALL_REVIEW_ALLOWED_TOOLS,
+        "--disallowedTools",
+        *ALL_REVIEW_DISALLOWED_TOOLS,
+        "--settings",
+        REVIEW_SETTINGS_TEXT,
+    ]
+
+
+def _review_environment() -> dict[str, str]:
+    all_child_environment_variables = {
+        each_name: each_value
+        for each_name, each_value in os.environ.items()
+        if each_name not in ALL_PARENT_SESSION_VARIABLES
+    }
+    all_child_environment_variables[REVIEW_CHILD_ENVIRONMENT_VARIABLE] = REVIEW_CHILD_MARKER
+    return all_child_environment_variables
+
+
+def _write_review_failure(repository_root: Path, failure_text: str) -> None:
+    sys.stderr.write(
+        REVIEW_FAILURE_DIAGNOSTIC_TEMPLATE.format(
+            repository=repository_root.name, reason=failure_text
+        )
+    )
+
+
+def _review_stdout(
+    repository_root: Path, base_commit: str, turn_commit: str, remaining_seconds: float
+) -> str | None:
+    try:
+        completed_process = subprocess.run(
+            _review_command(base_commit, turn_commit),
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            stdin=subprocess.DEVNULL,
+            timeout=remaining_seconds,
+            cwd=str(repository_root),
+            env=_review_environment(),
+            creationflags=hidden_window_creation_flags(),
+        )
+    except subprocess.TimeoutExpired:
+        _write_review_failure(repository_root, "timed out")
+        return None
+    except OSError as start_error:
+        _write_review_failure(repository_root, str(start_error))
+        return None
+    if completed_process.returncode != 0:
+        _write_review_failure(repository_root, f"exit {completed_process.returncode}")
+        return None
+    return completed_process.stdout
+
+
+def _review_text(
+    repository_root: Path, base_commit: str, turn_commit: str, review_deadline: float
+) -> str | None:
+    remaining_seconds = review_deadline - time.monotonic()
+    if remaining_seconds < MINIMUM_REVIEW_SECONDS:
+        _write_review_failure(repository_root, "no review time left this stop")
+        return None
+    review_stdout = _review_stdout(repository_root, base_commit, turn_commit, remaining_seconds)
+    if review_stdout is None:
+        return None
+    try:
+        review_result = json.loads(review_stdout)
+    except ValueError:
+        _write_review_failure(repository_root, "output was not JSON")
+        return None
+    review_text = review_result.get(REVIEW_RESULT_KEY) if isinstance(review_result, dict) else None
+    if not isinstance(review_text, str):
+        _write_review_failure(repository_root, "output had no result text")
+        return None
+    return review_text
+
+
+def _state_path(session_id: object) -> Path:
+    return Path(tempfile.gettempdir()) / STATE_FILE_TEMPLATE.format(
+        session_id=session_file_id(session_id)
+    )
+
+
+def _load_state(session_id: object) -> tuple[dict[str, str], int]:
+    try:
+        saved_state = json.loads(_state_path(session_id).read_text(encoding=STATE_TEXT_ENCODING))
+    except (OSError, ValueError):
+        return {}, 0
+    if not isinstance(saved_state, dict):
+        return {}, 0
+    raw_baselines = saved_state.get(STATE_BASELINES_KEY)
+    all_baselines = {
+        each_root: each_commit
+        for each_root, each_commit in (
+            raw_baselines.items() if isinstance(raw_baselines, dict) else []
+        )
+        if isinstance(each_root, str)
+        and isinstance(each_commit, str)
+        and re.fullmatch(BASELINE_COMMIT_PATTERN, each_commit)
+    }
+    raw_blocks = saved_state.get(STATE_BLOCKS_KEY)
+    return all_baselines, raw_blocks if isinstance(raw_blocks, int) else 0
+
+
+def _save_state(session_id: object, all_baselines: dict[str, str], blocks_in_a_row: int) -> None:
+    write_text_atomically(
+        _state_path(session_id),
+        json.dumps({STATE_BASELINES_KEY: all_baselines, STATE_BLOCKS_KEY: blocks_in_a_row}),
+        STATE_TEXT_ENCODING,
+        STATE_TEMPORARY_PREFIX,
+        ATOMIC_WRITE_TEMPORARY_SUFFIX,
+        False,
+    )
+
+
+def _record_prompt_baselines(session_id: object, all_roots: list[Path]) -> None:
+    all_baselines = {}
+    for each_root in all_roots:
+        snapshot_commit = working_tree_snapshot(each_root, None)
+        if snapshot_commit is not None:
+            all_baselines[str(each_root)] = snapshot_commit
+    _save_state(session_id, all_baselines, 0)
+
+
+def _repository_findings(
+    repository_root: Path, base_commit: str, turn_commit: str, review_deadline: float
+) -> str | None:
+    all_changed_paths = turn_changed_paths(repository_root, base_commit, turn_commit)
+    if len(all_changed_paths) > MAXIMUM_TURN_FILES:
+        sys.stderr.write(
+            TOO_MANY_FILES_DIAGNOSTIC_TEMPLATE.format(
+                repository=repository_root.name,
+                count=len(all_changed_paths),
+                limit=MAXIMUM_TURN_FILES,
+            )
+        )
+        return None
+    if not all_changed_paths:
+        return None
+    review_text = _review_text(repository_root, base_commit, turn_commit, review_deadline)
+    all_finding_lines = finding_lines(review_text or "", all_changed_paths)
+    if not all_finding_lines:
+        return None
+    return REPOSITORY_FINDINGS_TEMPLATE.format(
+        repository=repository_root.name,
+        findings=FINDING_LINE_SEPARATOR.join(all_finding_lines),
+    )
+
+
+def _turn_block_reason(session_id: object, all_roots: list[Path]) -> str | None:
+    all_baselines, blocks_in_a_row = _load_state(session_id)
+    all_next_baselines: dict[str, str] = {}
+    all_findings: list[str] = []
+    review_deadline = time.monotonic() + REVIEW_TIMEOUT_SECONDS
+    for each_root in all_roots:
+        base_commit = all_baselines.get(str(each_root))
+        turn_commit = working_tree_snapshot(each_root, base_commit)
+        if turn_commit is None:
+            continue
+        all_next_baselines[str(each_root)] = turn_commit
+        if base_commit is None or blocks_in_a_row >= MAXIMUM_BLOCKS_IN_A_ROW:
+            continue
+        repository_findings = _repository_findings(
+            each_root, base_commit, turn_commit, review_deadline
+        )
+        if repository_findings is not None:
+            all_findings.append(repository_findings)
+    if all_findings:
+        blocks_in_a_row += 1
+    elif blocks_in_a_row < MAXIMUM_BLOCKS_IN_A_ROW:
+        blocks_in_a_row = 0
+    _save_state(session_id, all_next_baselines, blocks_in_a_row)
+    if not all_findings:
+        return None
+    return BLOCK_REASON_TEMPLATE.format(
+        all_findings=REPOSITORY_FINDINGS_SEPARATOR.join(all_findings)
+    )
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return 0
+    if os.environ.get(REVIEW_CHILD_ENVIRONMENT_VARIABLE) == REVIEW_CHILD_MARKER:
+        return 0
+    all_slugs = _opted_in_repository_slugs()
+    if not all_slugs:
+        return 0
+    all_roots = _opted_in_repository_roots(all_slugs)
+    if not all_roots:
+        return 0
+    session_id = hook_input.get(SESSION_ID_KEY)
+    hook_event_name = hook_input.get(HOOK_EVENT_NAME_KEY)
+    if hook_event_name == PROMPT_EVENT_NAME:
+        _record_prompt_baselines(session_id, all_roots)
+        return 0
+    if hook_event_name != STOP_EVENT_NAME:
+        return 0
+    block_reason = _turn_block_reason(session_id, all_roots)
+    if block_reason is None:
+        return 0
+    log_hook_block(Path(__file__).name, STOP_EVENT_NAME, block_reason)
+    sys.stdout.write(json.dumps({DECISION_KEY: BLOCK_DECISION, REASON_KEY: block_reason}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/turn_review_snapshot.py

@@ -0,0 +1,116 @@
+"""Snapshot a checkout's working tree as a commit, for the turn review Stop gate.
+
+A snapshot is a commit built from a copy of the repository's index after
+``git add -A``, so untracked files count and the user's own index stays as it
+was::
+
+    prompt  ->  working_tree_snapshot(root, None)  ->  A  (parent HEAD)
+    stop    ->  working_tree_snapshot(root, A)     ->  B  (parent A)
+    turn_changed_paths(root, A, B)                 ->  ["src/service.py"]
+
+Chaining each snapshot onto the last one makes ``A..B`` a single commit that
+holds only the edits made between the two calls.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+from hooks_constants.turn_review_gate_constants import (
+    ALL_CHANGED_PATH_ARGUMENTS,
+    ALL_INDEX_PATH_ARGUMENTS,
+    ALL_SNAPSHOT_IDENTITY_VARIABLES,
+    CHANGED_PATH_SEPARATOR,
+    GIT_COMMAND_TIMEOUT_SECONDS,
+    GIT_OUTPUT_ENCODING,
+    GIT_OUTPUT_ERROR_HANDLING,
+    GIT_INDEX_FILE_ENVIRONMENT_VARIABLE,
+    SNAPSHOT_COMMIT_MESSAGE,
+    TEMPORARY_INDEX_FILE_NAME,
+)
+
+
+def _git_output(
+    repository_root: Path,
+    all_arguments: list[str],
+    all_environment_variables: dict[str, str] | None,
+) -> str | None:
+    try:
+        completed_process = subprocess.run(
+            ["git", *all_arguments],
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding=GIT_OUTPUT_ENCODING,
+            errors=GIT_OUTPUT_ERROR_HANDLING,
+            timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            cwd=str(repository_root),
+            env=all_environment_variables,
+            creationflags=hidden_window_creation_flags(),
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if completed_process.returncode != 0:
+        return None
+    return completed_process.stdout.rstrip("\n")
+
+
+def _working_tree_object(repository_root: Path) -> str | None:
+    index_path_text = _git_output(repository_root, list(ALL_INDEX_PATH_ARGUMENTS), None)
+    if index_path_text is None:
+        return None
+    with tempfile.TemporaryDirectory() as index_directory:
+        temporary_index = Path(index_directory) / TEMPORARY_INDEX_FILE_NAME
+        try:
+            shutil.copyfile(repository_root / index_path_text, temporary_index)
+        except OSError:
+            return None
+        all_index_environment_variables = {
+            **os.environ,
+            GIT_INDEX_FILE_ENVIRONMENT_VARIABLE: str(temporary_index),
+        }
+        if _git_output(repository_root, ["add", "-A"], all_index_environment_variables) is None:
+            return None
+        return _git_output(repository_root, ["write-tree"], all_index_environment_variables)
+
+
+def working_tree_snapshot(repository_root: Path, base_commit: str | None) -> str | None:
+    """Return a commit that holds the working tree as it is now.
+
+    Args:
+        repository_root: The checkout to snapshot.
+        base_commit: The previous snapshot, used as the parent. None uses HEAD.
+
+    Returns:
+        The snapshot commit, ``base_commit`` itself when the tree has not
+        changed since it, or None when git cannot build one.
+    """
+    tree = _working_tree_object(repository_root)
+    if tree is None:
+        return None
+    if (
+        base_commit
+        and _git_output(repository_root, ["rev-parse", f"{base_commit}^{{tree}}"], None) == tree
+    ):
+        return base_commit
+    parent = base_commit or "HEAD"
+    return _git_output(
+        repository_root,
+        ["commit-tree", tree, "-p", parent, "-m", SNAPSHOT_COMMIT_MESSAGE],
+        {**os.environ, **ALL_SNAPSHOT_IDENTITY_VARIABLES},
+    )
+
+
+def turn_changed_paths(repository_root: Path, base_commit: str, turn_commit: str) -> list[str]:
+    """Return the repository-relative paths that differ between two snapshots."""
+    if base_commit == turn_commit:
+        return []
+    diff_names = _git_output(
+        repository_root, [*ALL_CHANGED_PATH_ARGUMENTS, base_commit, turn_commit], None
+    )
+    return [each for each in (diff_names or "").split(CHANGED_PATH_SEPARATOR) if each]

package/hooks/features/conduct-gates.md

@@ -24,6 +24,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/merge_over_review_offer_gate.py` denies a decision card or question that offers a merge while it names open review findings, a red check, unaddressed review comments, or an override. It reads the whole card as one text: every question, header, context, reason, and option, whether the option is a string or a label with a consequence or description.
 - `blocking/artifact_dark_mode_gate.py` denies an Artifact page publish when the page, inside the publish wrapper, keeps a light body or shows text under 4.5:1 contrast in dark mode. `blocking/artifact_dark_mode_render.cjs` renders the page in headless Chromium for it.
 - `blocking/send_user_file_worktree_root_gate.py` denies a `SendUserFile` call that names a file outside the session's working directory, the `cwd` in the hook payload. The desktop file pane opens a sent file only under that folder and shows "Couldn't find this file" for any other path. The reason lists each outside file and names `<cwd>\.scratch\` as the folder to copy it into.
+- `blocking/turn_review_gate.py` holds the end of a turn when a fresh `claude -p "/code-review low <base>..<turn>"` run finds a problem in that turn's edits. At the prompt it snapshots each opted-in checkout into a commit built from a copy of the index after `git add -A`; at the stop it snapshots again with the first snapshot as parent, so the range holds only the turn's edits, untracked files included. A checkout takes part when it is `CLAUDE_PROJECT_DIR` or a folder directly inside it and its GitHub origin `owner/repo` slug is listed in `CLAUDE_TURN_REVIEW_REPOSITORIES`, comma-separated. A finding is an entry in the review's last non-empty JSON array of objects with a `file` key, where `file` is a changed path and `line` is a number. An empty `[]` counts as no array. A review with no such array has a finding on each line that opens with a changed path, a colon and a line number, after an optional list marker, backtick or emphasis mark. A review that opens with `(none)` has none. A saved baseline that is not a 40- or 64-character commit name is dropped, and that stop takes a fresh baseline. Each stop moves the baseline to its snapshot, so the stop after a block reviews only the fix. It holds a stop at most 3 times in a row until the next prompt, skips a turn that changed more than 30 files, and lets the stop through when the review fails. The reviews of one stop share 240 seconds, and a checkout reached with less than a second left goes unreviewed. The review run gets `--setting-sources ""`, `--tools Read,Grep,Glob,Bash`, `--no-session-persistence`, `--permission-mode dontAsk`, read tools plus `git diff`, `git show` and `git log` in the checkout, a deny list for git's `-c`, `--config-env`, `--output`, `--ext-diff`, `--textconv`, `--git-dir`, `--work-tree` and `--exec-path` options, `--settings '{"disableAllHooks": true}'` so no other hook steers the review, `CLAUDE_TURN_REVIEW_CHILD=1`, and none of the parent session's id, messaging or ingress variables; the gate does nothing inside such a run.
 
 ## When it fires
 
@@ -47,6 +48,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/merge_over_review_offer_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion|mcp__.*__ask_decision`, timeout `10` seconds in `hooks.json`.
 - `blocking/artifact_dark_mode_gate.py` runs on `PreToolUse`, matcher `Artifact`, timeout `60` seconds in `hooks.json`.
 - `blocking/send_user_file_worktree_root_gate.py` runs on `PreToolUse`, matcher `SendUserFile`, timeout `10` seconds in `hooks.json`.
+- `blocking/turn_review_gate.py` runs on `UserPromptSubmit`, matcher empty, timeout `30` seconds, and on `Stop`, timeout `300` seconds, in `hooks.json`. The review itself times out after 240 seconds.
 
 ## Proving it
 
@@ -74,10 +76,13 @@ Preconditions:
 - **Merge offer.** Input is a decision card or AskUserQuestion that offers "Merge now", the merge queue, or a yes to "Merge it now?" while any part of the card names open findings or unaddressed review comments. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_merge_over_review_offer_gate.py -q`. The adjacent test observes a denial for each, including an offer and findings in separate questions; a card with no merge offer, a card about the merge review check itself, a card about shipping a docs change, and a merge offer after a clean review pass.
 - **Dark mode page.** Input is an Artifact publish of a page that themes `html` but leaves `body` to the publish wrapper. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_artifact_dark_mode_gate.py -q`. The adjacent test observes a denial that names the text and its contrast; a page that themes `body` passes. The render tests skip on a host with no Node Playwright and Chromium.
 - **Sent file root.** Input is a `SendUserFile` call for a file on `Y:\` or in the session scratchpad, with `cwd` set to a worktree. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_send_user_file_worktree_root_gate.py -q`. The adjacent test observes a denial that names the file and `<cwd>\.scratch\`; a file under `<cwd>\.scratch\` passes.
+- **Turn review.** Input is a temporary checkout with an opted-in origin, a `UserPromptSubmit`, an edit that drops a decorator, and a `Stop`, with a stub `claude` on PATH that prints a finding. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_turn_review_gate.py -q`. The adjacent test observes a `block` decision with the finding, a review range whose diff holds only the edited file, and a review environment with no parent session id. A `(none)` review, an unchanged turn, a failed review, an unlisted repository, a 31-file turn, and a fourth stop in a row pass.
 
 ## Gotchas
 
 - The ask nudge runs only from `hooks.json`, so Codex and Cursor sessions get no turn-start note. Their Stop gate still holds a work turn with no tracker call.
+- `blocking/turn_review_gate.py` starts `claude -p`, which inherits the parent session id unless the gate strips it. A review that kept `CLAUDE_CODE_SESSION_ID` would write into the parent's transcript.
+- Each review run calls a model and costs about $0.03. Leave `CLAUDE_TURN_REVIEW_REPOSITORIES` unset and the gate makes no snapshot and no call.
 - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.

package/hooks/hooks.json

@@ -343,6 +343,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/plugin_change_warning.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/turn_review_gate.py",
+            "timeout": 30
           }
         ]
       }
@@ -449,6 +454,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_title_turn_gate.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/turn_review_gate.py",
+            "timeout": 300
           }
         ]
       }

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -20,7 +20,8 @@ MISSING_PROOF_REASON = (
     " the difference. For a hook, skill, rule, setting, prompt or output style, spawn"
     " each test session through the account broker. Then add a 'Proof in practice'"
     " heading to the body that lists each command in backticks, quotes the output, states"
-    " the difference between the runs, and names anything still unproven. When you cannot"
+    " the difference between the runs, and lists any condition the runs left out under a"
+    " 'Not covered' heading. When you cannot"
     " prove the change, leave the pull request unopened and tell the user what you could"
     " not run. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
@@ -62,6 +63,18 @@ TEST_ONLY_PROOF_REASON = (
     " command in backticks and quote the output lines that show the difference. Keep the"
     " test run in the section as extra evidence. Read " + PROOF_GUIDE_PATH + " for the full rule."
 )
+UNPROVEN_ADMISSION_PATTERN = r"\b(?:not (?:(?:yet|been|fully) )*(?:proven|tested|verified)|unproven|untested|unverified)\b"
+INLINE_CODE_SPAN_PATTERN = r"`[^`\n]*`"
+BLOCKQUOTE_MARKERS = "> "
+ALL_CODE_FENCE_MARKERS = ("```", "~~~")
+UNPROVEN_PROOF_REASON = (
+    "This pull request's 'Proof in practice' section says part of the change is not"
+    " proven: \"{admission}\". When that part is what the change exists to do, such as"
+    " the run on the target that failed, leave the pull request unopened. Run it, quote"
+    " its output, then open the pull request. When it is a condition the change does not"
+    " target, move the line under a 'Not covered' heading at the same level as the proof"
+    " heading. Read " + PROOF_GUIDE_PATH + " for the full rule."
+)
 EXISTING_WORK_HEADING_PATTERN = r"^(#{1,6})[ \t]+existing work[ \t]*#*[ \t]*$"
 EXISTING_WORK_GUIDE_PATH = "~/.claude/docs/rule-guides/explore-thoroughly.md"
 MISSING_EXISTING_WORK_REASON = (