claude-dev-env 2.31.1 → 2.32.0

package/hooks/hooks_constants/piped_pytest_blocker_constants.py

@@ -91,7 +91,9 @@ bare, quoted, or backslash-escaped (``<<\\EOF`` quotes the delimiter the way
 ``<<'EOF'`` does). ``<<<`` is a here-string rather than a heredoc, so the
 pattern refuses to read one as an opener and leave the lines below it unread.
 The opener also reports its own ``-``, because ``<<`` closes on a line spelling
-the delimiter exactly while ``<<-`` closes on one carrying leading tabs.
+the delimiter exactly while ``<<-`` closes on one carrying leading tabs. It
+reports the quote and the backslash separately from the delimiter word, because
+either one tells a caller that bash expands nothing inside the body below.
 
 The string-executing shell basenames and command flags start from the shared
 ``unscoped_search_blocker_constants.py`` sets and add the Windows command shell
@@ -167,8 +169,10 @@ __all__ = [
     "HEREDOC_OPENER_PATTERN",
     "HEREDOC_TAB_STRIP_GROUP",
     "HEREDOC_QUOTE_GROUP",
+    "HEREDOC_ESCAPE_GROUP",
     "HEREDOC_TERMINATOR_GROUP",
     "HEREDOC_TAB_STRIP_MARKER",
+    "HEREDOC_UNQUOTED_MARKER",
     "HEREDOC_STRIPPED_INDENT_CHARACTERS",
     "NO_FOLLOWING_OPERATOR",
     "ALL_QUOTE_CHARACTERS",
@@ -340,13 +344,16 @@ CLOSED_GROUP_DEPTH = 0
 _HEREDOC_DELIMITER_CHARACTER_CLASS = r"[^\s'\"<>|&;()`$\\]"
 HEREDOC_TAB_STRIP_GROUP = "heredoc_tab_strip"
 HEREDOC_QUOTE_GROUP = "heredoc_quote"
+HEREDOC_ESCAPE_GROUP = "heredoc_escape"
 HEREDOC_TERMINATOR_GROUP = "heredoc_terminator"
 HEREDOC_OPENER_PATTERN = re.compile(
-    rf"(?<!<)<<(?!<)(?P<{HEREDOC_TAB_STRIP_GROUP}>-?)\s*(?P<{HEREDOC_QUOTE_GROUP}>['\"]?)\\?"
+    rf"(?<!<)<<(?!<)(?P<{HEREDOC_TAB_STRIP_GROUP}>-?)\s*(?P<{HEREDOC_QUOTE_GROUP}>['\"]?)"
+    rf"(?P<{HEREDOC_ESCAPE_GROUP}>\\?)"
     rf"(?P<{HEREDOC_TERMINATOR_GROUP}>{_HEREDOC_DELIMITER_CHARACTER_CLASS}+)"
     rf"(?P={HEREDOC_QUOTE_GROUP})"
 )
 HEREDOC_TAB_STRIP_MARKER = "-"
+HEREDOC_UNQUOTED_MARKER = ""
 HEREDOC_STRIPPED_INDENT_CHARACTERS = "\t"
 NO_FOLLOWING_OPERATOR = ""
 ALL_QUOTE_CHARACTERS = "\"'"

package/hooks/hooks_constants/shell_substitution_blocker_constants.py

@@ -25,6 +25,11 @@ __all__ = [
     "PROCESS_SUBSTITUTION_PATTERN",
     "SINGLE_QUOTED_RUN_PATTERN",
     "STRIPPED_RUN_REPLACEMENT",
+    "COMMAND_LINE_SEPARATOR",
+    "BACKSLASH_CHARACTER",
+    "SINGLE_QUOTE_CHARACTER",
+    "DOUBLE_QUOTE_CHARACTER",
+    "NO_TERMINATOR_INDEX",
     "CORRECTIVE_MESSAGE",
 ]
 
@@ -49,6 +54,11 @@ EVEN_BACKSLASH_BACKTICK_PATTERN = re.compile(r"(?<!\\)(?:\\\\)*`")
 PROCESS_SUBSTITUTION_PATTERN = re.compile(r"[<>]\(")
 SINGLE_QUOTED_RUN_PATTERN = re.compile(r"'[^']*'")
 STRIPPED_RUN_REPLACEMENT = ""
+COMMAND_LINE_SEPARATOR = "\n"
+BACKSLASH_CHARACTER = "\\"
+SINGLE_QUOTE_CHARACTER = "'"
+DOUBLE_QUOTE_CHARACTER = '"'
+NO_TERMINATOR_INDEX = -1
 
 CORRECTIVE_MESSAGE = (
     "BLOCKED [shell-substitution]: command contains $(...), backtick, or "

package/hooks/hooks_constants/state_file_lock.py

@@ -0,0 +1,76 @@
+"""Hold a best-effort exclusive lock across one read-modify-write of a state file.
+
+Two hooks can reach the same state file in one turn. The file is written
+through a temporary-plus-replace, so it is never torn; what this closes is
+the separate lost-update race, where one writer reads before the other
+writes and then overwrites it.
+
+::
+
+    with hold_state_file_lock(state_file):
+        all_stored = read(state_file)
+        write(state_file, updated(all_stored))
+
+The lock is best effort. A caller that cannot take it inside the timeout
+proceeds without it rather than stalling the tool call that triggered it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sys
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
+    LOCK_ACQUIRE_RETRY_SECONDS,
+    LOCK_ACQUIRE_TIMEOUT_SECONDS,
+    SESSION_EDIT_LOCK_FILE_SUFFIX,
+)
+
+
+def _acquire_lock_descriptor(lock_file: Path) -> int | None:
+    """Grab the exclusive lock, spinning until it frees or the timeout passes.
+
+    Args:
+        lock_file: Path to the lock file beside the state file.
+
+    Returns:
+        An open descriptor for the held lock, or None when it stayed held
+        past the acquire timeout.
+    """
+    lock_acquire_deadline = time.monotonic() + LOCK_ACQUIRE_TIMEOUT_SECONDS
+    while True:
+        try:
+            return os.open(str(lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            if time.monotonic() >= lock_acquire_deadline:
+                return None
+            time.sleep(LOCK_ACQUIRE_RETRY_SECONDS)
+
+
+@contextlib.contextmanager
+def hold_state_file_lock(state_file: Path) -> Iterator[None]:
+    """Hold the lock beside one state file for the body of the with-block.
+
+    Args:
+        state_file: The state file whose read-modify-write is being guarded.
+
+    Yields:
+        Control to the caller while the lock is held.
+    """
+    lock_file = state_file.with_name(state_file.name + SESSION_EDIT_LOCK_FILE_SUFFIX)
+    lock_file.parent.mkdir(parents=True, exist_ok=True)
+    lock_descriptor = _acquire_lock_descriptor(lock_file)
+    try:
+        yield
+    finally:
+        if lock_descriptor is not None:
+            os.close(lock_descriptor)
+            lock_file.unlink(missing_ok=True)

package/hooks/hooks_constants/test_bash_post_call_dispatcher_constants.py

@@ -0,0 +1,27 @@
+"""Behavioral tests for the Bash PostToolUse dispatcher's hosted-hook roster."""
+
+from hooks_constants.bash_post_call_dispatcher_constants import (
+    ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES,
+)
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import BASH_TOOL_NAME
+
+
+def test_roster_names_the_gh_pr_author_restore_hook() -> None:
+    all_script_paths = [
+        each_entry.script_relative_path for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
+    ]
+    assert "blocking/gh_pr_author_restore.py" in all_script_paths
+
+
+def test_roster_names_the_test_failure_recorder_hook() -> None:
+    all_script_paths = [
+        each_entry.script_relative_path for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
+    ]
+    assert "observability/test_failure_recorder.py" in all_script_paths
+
+
+def test_every_roster_entry_applies_to_bash() -> None:
+    assert all(
+        BASH_TOOL_NAME in each_entry.applicable_tool_names
+        for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
+    )

package/hooks/hooks_constants/test_failure_recorder_constants.py

@@ -0,0 +1,35 @@
+"""Constants for the failing-test-run PostToolUse recorder hook.
+
+Holds the cheap substring check the hook runs before any shell parsing, the
+harness's own exit-code error prefix, the chaining and redirection operator
+tokens that keep the recognizer to one unchained command, the pytest program
+and Python interpreter basenames, and the flag-token marker the path
+extractor uses to skip an option rather than an existing test file argument.
+
+``BASH_TOOL_NAME`` lives in ``gh_pr_author_swap_constants`` already; this
+module reuses that name rather than a second literal. The pytest-program and
+interpreter recognition here is deliberately its own small, stdlib-only
+check rather than a reuse of ``piped_pytest_blocker_constants`` /
+``pytest_invocation``: those solve the harder pipe-and-wrapper problem and
+pull in a much larger transitive import for every Bash call regardless of
+content, working against the point of the recognizer's own cheap prefilter.
+"""
+
+from __future__ import annotations
+
+import re
+
+ALL_PYTEST_MENTION_SUBSTRINGS: tuple[str, ...] = ("pytest", "py.test")
+EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
+OPTION_TOKEN_PREFIX: str = "-"
+NODE_ID_FILE_PATH_SEPARATOR: str = "::"
+ALL_CHAINING_OPERATOR_SUBSTRINGS: tuple[str, ...] = ("&&", "||", ";", "|", "\n")
+ALL_REDIRECTION_TOKENS: frozenset[str] = frozenset(
+    {">", ">>", "<", "<<", "2>&1", "1>&2", "2>", "1>"}
+)
+ALL_PYTEST_PROGRAM_BASENAMES: frozenset[str] = frozenset({"pytest", "py.test"})
+MODULE_RUN_FLAG: str = "-m"
+PYTEST_MODULE_NAME: str = "pytest"
+PYTHON_INTERPRETER_BASENAME_PATTERN: re.Pattern[str] = re.compile(
+    r"^(?:python|py|pypy)[0-9.]*(?:\.exe)?$"
+)

package/hooks/hooks_constants/test_hosted_hook_runner.py

@@ -7,15 +7,22 @@ and the restoration of the interpreter's stdin, stdout, and argv.
 
 from __future__ import annotations
 
+import io
 import json
 import sys
 from pathlib import Path
 
+import pytest
+
 _HOOKS_DIR = str(Path(__file__).resolve().parent.parent)
 if _HOOKS_DIR not in sys.path:
     sys.path.insert(0, _HOOKS_DIR)
 
-from hooks_constants.hosted_hook_runner import HostedHookRun, run_hook_capturing_output  # noqa: E402
+from hooks_constants.hosted_hook_runner import (  # noqa: E402
+    HostedHookRun,
+    run_dispatcher_main,
+    run_hook_capturing_output,
+)
 
 
 def _write_probe(tmp_path: Path, body: str) -> str:
@@ -99,3 +106,50 @@ def test_returns_a_hosted_hook_run_instance(tmp_path: Path) -> None:
     probe_path = _write_probe(tmp_path, "print('x')\n")
     hook_run = run_hook_capturing_output(probe_path, "{}")
     assert isinstance(hook_run, HostedHookRun)
+
+
+def test_run_dispatcher_main_calls_dispatch_with_payload_text_and_tool_name(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A well-formed payload reaches dispatch with its JSON text and tool_name."""
+    all_calls: list[tuple[str, str]] = []
+    monkeypatch.setattr(
+        sys, "stdin", io.StringIO(json.dumps({"tool_name": "Bash", "tool_input": {}}))
+    )
+
+    with pytest.raises(SystemExit) as raised_exit:
+        run_dispatcher_main(lambda payload_text, tool_name: all_calls.append((payload_text, tool_name)))
+
+    assert int(raised_exit.value.code or 0) == 0
+    assert len(all_calls) == 1
+    recorded_payload_text, recorded_tool_name = all_calls[0]
+    assert recorded_tool_name == "Bash"
+    assert json.loads(recorded_payload_text)["tool_name"] == "Bash"
+
+
+def test_run_dispatcher_main_skips_dispatch_for_malformed_stdin(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Unparseable stdin exits zero and never calls dispatch."""
+    all_calls: list[tuple[str, str]] = []
+    monkeypatch.setattr(sys, "stdin", io.StringIO("not json"))
+
+    with pytest.raises(SystemExit) as raised_exit:
+        run_dispatcher_main(lambda payload_text, tool_name: all_calls.append((payload_text, tool_name)))
+
+    assert int(raised_exit.value.code or 0) == 0
+    assert all_calls == []
+
+
+def test_run_dispatcher_main_skips_dispatch_when_tool_name_is_missing(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A payload with no tool_name exits zero and never calls dispatch."""
+    all_calls: list[tuple[str, str]] = []
+    monkeypatch.setattr(sys, "stdin", io.StringIO(json.dumps({"tool_input": {}})))
+
+    with pytest.raises(SystemExit) as raised_exit:
+        run_dispatcher_main(lambda payload_text, tool_name: all_calls.append((payload_text, tool_name)))
+
+    assert int(raised_exit.value.code or 0) == 0
+    assert all_calls == []

package/hooks/observability/session_file_edit_tracker.py

@@ -18,13 +18,10 @@ never interrupts the edit that triggered it.
 
 from __future__ import annotations
 
-import contextlib
 import json
 import os
 import sys
 import tempfile
-import time
-from collections.abc import Iterator
 from pathlib import Path
 
 _hooks_dir = str(Path(__file__).resolve().parent.parent)
@@ -35,15 +32,13 @@ from blocking.codex_apply_patch import payload_patch_target_paths  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )
+from hooks_constants.state_file_lock import hold_state_file_lock  # noqa: E402
 from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
     ALL_EDITED_FILE_PATHS_KEY,
     ALL_TRACKED_EDIT_TOOL_NAMES,
     APPLY_PATCH_TOOL_NAME,
-    LOCK_ACQUIRE_RETRY_SECONDS,
-    LOCK_ACQUIRE_TIMEOUT_SECONDS,
     SESSION_EDIT_FILE_PREFIX,
     SESSION_EDIT_FILE_SUFFIX,
-    SESSION_EDIT_LOCK_FILE_SUFFIX,
     SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
     STATE_FILE_ATOMIC_WRITE_SUFFIX,
     STATE_FILE_DEFAULT_SESSION_ID,
@@ -140,54 +135,6 @@ def _atomic_write_edit_file(edit_file: Path, all_edited_file_paths: list[str]) -
         raise
 
 
-def _acquire_edit_file_lock(lock_file: Path) -> int | None:
-    """Grab an exclusive per-session lock, spinning until it frees or times out.
-
-    Args:
-        lock_file: Path to this session's lock file.
-
-    Returns:
-        An open file descriptor for the held lock, or None when the lock stayed
-        held past the acquire timeout so the caller proceeds without it rather
-        than stalling the edit that triggered the hook.
-    """
-    lock_acquire_deadline = time.monotonic() + LOCK_ACQUIRE_TIMEOUT_SECONDS
-    while True:
-        try:
-            return os.open(str(lock_file), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
-        except FileExistsError:
-            if time.monotonic() >= lock_acquire_deadline:
-                return None
-            time.sleep(LOCK_ACQUIRE_RETRY_SECONDS)
-
-
-@contextlib.contextmanager
-def _hold_edit_file_lock(edit_file: Path) -> Iterator[None]:
-    """Hold the per-session lock across one read-modify-write of the tracker.
-
-    Two PostToolUse invocations run concurrently when Claude issues parallel
-    Write or Edit calls in one turn. Serializing the read-then-write on a shared
-    lock file keeps each invocation's appended path from overwriting another's.
-    The lock is best-effort: when it cannot be acquired within the timeout, the
-    write proceeds without it rather than stalling the edit.
-
-    Args:
-        edit_file: This session's tracker file path.
-
-    Yields:
-        Control to the caller while the lock is held.
-    """
-    lock_file = edit_file.with_name(edit_file.name + SESSION_EDIT_LOCK_FILE_SUFFIX)
-    lock_file.parent.mkdir(parents=True, exist_ok=True)
-    lock_descriptor = _acquire_edit_file_lock(lock_file)
-    try:
-        yield
-    finally:
-        if lock_descriptor is not None:
-            os.close(lock_descriptor)
-            lock_file.unlink(missing_ok=True)
-
-
 def _record_edited_path(session_id: str, resolved_file_path: str) -> None:
     """Append one edited path to this session's tracker file when it is new.
 
@@ -200,7 +147,7 @@ def _record_edited_path(session_id: str, resolved_file_path: str) -> None:
         resolved_file_path: The resolved absolute path of the edited file.
     """
     edit_file = _session_edit_file_path(session_id)
-    with _hold_edit_file_lock(edit_file):
+    with hold_state_file_lock(edit_file):
         recorded_paths = _read_recorded_paths(edit_file)
         if resolved_file_path in recorded_paths:
             return

package/hooks/observability/test_failure_recorder.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""PostToolUse hook: record a failing single pytest run as TDD-gate evidence.
+
+A file-content edit is not the same claim as a test that ran and failed. The
+content-hash store in ``tdd_enforcer_parts/content_hash_store.py`` already
+tracks whether a candidate test file's content changed; this hook adds a
+stronger form of evidence -- a real RED -- by watching every Bash call finish
+and, for a genuine failing pytest run, recording the command, its real exit
+status, and the test file paths it named into that same store.
+
+::
+
+    pytest test_orders.py                    (exit 1)  -> record test_orders.py
+    pytest test_orders.py -k fulfill          (exit 1)  -> record test_orders.py
+    pytest test_orders.py::test_fulfill       (exit 1)  -> record test_orders.py
+    pytest -q                                 (exit 1)  -> no path named, no record
+    cd repo && pytest test_orders.py          (exit 1)  -> chained, no record
+    pytest test_orders.py | tee run.log       (blocked by piped_pytest_blocker
+                                                first -- this hook never sees it)
+    npm test                                  (exit 1)  -> not pytest, no record
+    pytest test_orders.py                     (exit 0)  -> passed, no record
+
+What this hook matches, and why
+--------------------------------
+
+Only a single, unchained Bash command whose own program is ``pytest`` /
+``py.test``, or a Python interpreter running ``-m pytest``. A chained command
+(``&&``, ``;``, ``|``, ``||``, a newline) is rejected outright: this repo's own
+``piped_pytest_blocker.py`` already tells the caller to "run pytest alone" for
+exactly this reason, and a chain's reported exit status may belong to a
+command other than pytest, or to none of them if an earlier link short-
+circuited before pytest even ran. ``npm test``, ``node --test``, and
+``vitest`` are deliberately not matched: ``npm test`` is a script indirection
+whose real test runner lives in ``package.json``, not on the command line,
+and the other two have no existing, tested classification helper in this
+repository the way pytest does. Extending to them would mean inventing new
+parsing rather than reusing anything proven, which is the over-reach this
+mechanism is built to avoid.
+
+The recognizer here is deliberately its own small, stdlib-only ``shlex``
+check rather than a reuse of ``hooks_constants.pytest_invocation`` /
+``shell_command_pipeline``. Those solve the harder pipe-and-wrapper problem a
+PreToolUse blocker needs, and this repository's own style rule forbids an
+import inside a function body, so importing that larger machinery here would
+mean paying its full transitive import cost on every single Bash call this
+hook sees, pytest or not -- working directly against the point of watching
+every Bash call. The narrower, single-unchained-command scope this hook
+accepts does not need that machinery.
+
+Where the exit status comes from
+---------------------------------
+
+Not from scraping the command's output text for words like "failed" or
+"error". The Bash tool's own PostToolUse ``tool_response`` takes two shapes
+observed directly in this session's own transcript: a dict with ``stdout``/
+``stderr`` keys when the command's reported exit status is 0, and the literal
+string ``"Error: Exit code <N>\\n<output>"`` when it is not. This hook reads
+that harness-authored ``<N>`` directly; it is a real Bash mechanism doing the
+work correctly, not a lookalike that only mimics one.
+
+Where the test paths come from
+--------------------------------
+
+The command's own arguments, not its output. A bare ``pytest`` or ``pytest
+-q`` names no path and is left unrecorded on purpose: recording it against
+every test file pytest might have discovered would satisfy the gate for a
+file this run never demonstrably covered, which is the exact bypass the
+audit calls out. Only a token that is not an option flag and resolves to a
+real file on disk, relative to the command's own ``cwd``, counts.
+
+What stops a bypass
+---------------------
+
+Three things, together:
+
+1. ``content_hash_store.record_test_command_failure`` keys each entry
+   exactly as the gate looks candidates up, so a failure never satisfies a
+   sibling file the same command also happened to run (see
+   ``test_content_hash_store.py::test_recorded_failure_does_not_satisfy_a_different_candidate``).
+2. The gate consults a recorded failure only while the file's *current*
+   content hash still matches what actually failed (see
+   ``test_recorded_failure_does_not_apply_once_content_no_longer_matches``).
+   Editing the test again clears it as evidence.
+3. A record ages out after the same freshness window every other form of
+   evidence uses (see ``test_recorded_failure_expires_after_the_freshness_window``).
+
+The hook never blocks a tool call. A non-Bash tool, a malformed payload, a
+command that does not mention "pytest", a chained command, a command with no
+real path argument, or a failed record each returns quietly.
+"""
+
+from __future__ import annotations
+
+import shlex
+import sys
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    _blocking_directory = str(Path(_hooks_root_directory) / "blocking")
+    for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
+        if each_bootstrap_directory not in sys.path:
+            sys.path.insert(0, each_bootstrap_directory)
+    from hooks_constants.gh_pr_author_swap_constants import BASH_TOOL_NAME
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.test_failure_recorder_constants import (
+        ALL_CHAINING_OPERATOR_SUBSTRINGS,
+        ALL_PYTEST_MENTION_SUBSTRINGS,
+        ALL_PYTEST_PROGRAM_BASENAMES,
+        ALL_REDIRECTION_TOKENS,
+        EXIT_CODE_ERROR_PREFIX,
+        MODULE_RUN_FLAG,
+        NODE_ID_FILE_PATH_SEPARATOR,
+        OPTION_TOKEN_PREFIX,
+        PYTEST_MODULE_NAME,
+        PYTHON_INTERPRETER_BASENAME_PATTERN,
+    )
+    from tdd_enforcer_parts import content_hash_store
+except ImportError as import_error:
+    raise ImportError(
+        "test_failure_recorder: cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _mentions_pytest(command: str) -> bool:
+    lowered_command = command.lower()
+    return any(
+        each_substring in lowered_command for each_substring in ALL_PYTEST_MENTION_SUBSTRINGS
+    )
+
+
+def _harness_reported_exit_status(tool_response: object) -> int | None:
+    if not isinstance(tool_response, str) or not tool_response.startswith(EXIT_CODE_ERROR_PREFIX):
+        return None
+    remainder = tool_response[len(EXIT_CODE_ERROR_PREFIX) :]
+    digit_count = 0
+    while digit_count < len(remainder) and remainder[digit_count].isdigit():
+        digit_count += 1
+    return int(remainder[:digit_count]) if digit_count else None
+
+
+def _is_single_unchained_command(command: str) -> bool:
+    return not any(each_operator in command for each_operator in ALL_CHAINING_OPERATOR_SUBSTRINGS)
+
+
+def _runs_pytest_via_module_flag(all_tokens: list[str]) -> bool:
+    if MODULE_RUN_FLAG not in all_tokens:
+        return False
+    flag_index = all_tokens.index(MODULE_RUN_FLAG)
+    return flag_index + 1 < len(all_tokens) and all_tokens[flag_index + 1] == PYTEST_MODULE_NAME
+
+
+def _command_tokens_run_pytest(all_tokens: list[str]) -> bool:
+    if not all_tokens:
+        return False
+    first_basename = Path(all_tokens[0]).name
+    if first_basename in ALL_PYTEST_PROGRAM_BASENAMES:
+        return True
+    if not PYTHON_INTERPRETER_BASENAME_PATTERN.match(first_basename):
+        return False
+    return _runs_pytest_via_module_flag(all_tokens)
+
+
+def _existing_test_file_paths(all_tokens: list[str], cwd: str) -> list[Path]:
+    all_paths: list[Path] = []
+    for each_token in all_tokens:
+        if each_token.startswith(OPTION_TOKEN_PREFIX) or each_token in ALL_REDIRECTION_TOKENS:
+            continue
+        file_path_text = each_token.split(NODE_ID_FILE_PATH_SEPARATOR, 1)[0]
+        candidate_path = Path(cwd, file_path_text) if cwd else Path(file_path_text)
+        if candidate_path.is_file():
+            all_paths.append(candidate_path)
+    return all_paths
+
+
+def _command_tokens(command: str) -> list[str]:
+    try:
+        return shlex.split(command)
+    except ValueError:
+        return []
+
+
+def _record_pytest_failure(hook_payload: dict, command: str) -> None:
+    exit_status = _harness_reported_exit_status(hook_payload.get("tool_response"))
+    if exit_status is None or not _is_single_unchained_command(command):
+        return
+    all_tokens = _command_tokens(command)
+    if not _command_tokens_run_pytest(all_tokens):
+        return
+    cwd = str(hook_payload.get("cwd") or "")
+    all_test_file_paths = _existing_test_file_paths(all_tokens, cwd)
+    if not all_test_file_paths:
+        return
+    session_id = str(hook_payload.get("session_id") or "")
+    content_hash_store.record_test_command_failure(
+        all_test_file_paths, command, exit_status, session_id, cwd
+    )
+
+
+def main() -> None:
+    """Record one failing pytest run's evidence from a PostToolUse Bash payload.
+
+    Reads the payload from stdin. Returns quietly on every branch that is not
+    a genuine, single, unchained, path-naming pytest failure, so a logging
+    problem never surfaces as a blocked or altered tool call.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None or hook_payload.get("tool_name") != BASH_TOOL_NAME:
+        return
+    tool_input = hook_payload.get("tool_input")
+    command = tool_input.get("command", "") if isinstance(tool_input, dict) else ""
+    if not isinstance(command, str) or not _mentions_pytest(command):
+        return
+    _record_pytest_failure(hook_payload, command)
+
+
+if __name__ == "__main__":
+    main()