claude-dev-env 2.31.1 → 2.33.0

package/hooks/git-hooks/pull_request_handoff.py

@@ -28,5 +28,5 @@ def get_pull_request_url(repo_dir: Path) -> str | None:
 
 
 def build_pull_request_reminder(url: str) -> str:
-    prompt = "Review this pull request: <PR link>\n\nRead the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.\n\nFind the main thing this adds for a user, caller, or operator.\n\nWrite like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.\n\nYour job is not a dry API blurb. Your job is an illustrative before/after a person can picture.\n\nGold voice for titles and “What this adds”:\n\nThe theme package has a phone icon somewhere. We need to find it.\n\nBefore: yell “anyone know how to find icons?” and wait for a hand.\n\nAfter: call the finder by its name tag: “icon finder, go.”\n\nThat’s all “operation id” is — the finder’s name tag.\n\nRules for that voice:\n\nStart from a concrete scene (what’s in someone’s hand, what they’re hunting for).\nPrefer Before / After when the change is “how you ask” or “how you look it up.”\nUse picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.\nPrefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”\nWhen the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:\nDrop it and say what the person does with their hands, or\nKeep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.\nNever leave jargon unexplained. Never write as if the reader already knows the jargon.\nAdd a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).\nFew words. Small words. Clear on first read.\nReturn:\n\nRecommended title\n\nFew words. Small words. Clear on first read.\nSay what you hand it, what it does, and what you get back — or the Before/After of how you ask.\nPrefer picture words and spoken results.\nGood title: “Call the icon finder by its name tag instead of asking around”\nGood title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”\nBad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.\nUse “Add” only if it helps. Do not force it.\nNo vague words like “improve,” “enhance,” or “update.”\nReturn one title only.\nWhy this title fits\n\n1–2 short sentences in the same voice.\nIf needed, one Before / After beat, then what you get back.\nIf this section is needed to decode the title, rewrite the title.\nEvidence\n\nKey files or functions that support the title.\nIf you cannot read the PR or full diff, say so and do not propose a title.\n\nThen write a short, paste-ready PR description.\n\nUse this structure:\n\nWhat this adds\n1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature. If there are many changes, keep the main one. Mention others only if they explain the main one.\n\nWhy\nOne short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”\n\nVerification\nList only proof from the PR, CI, or your own checks.\n\nReported in the PR\n\n…\nChecked by you / CI here\n\n…\nRules:\n\nFew words. Small words. Clear on first read. ELI5 I-am-stupid mark.\nDo not invent behavior, tests, or benefits.\nStrip branch names, hashes, draft notes, agent notes, and merge notes.\nNo vague words like “improve,” “enhance,” or “update.”\nIllustrative first. Abstract labels only if glossed in the same breath.\nUse the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result."
+    prompt = "Review this pull request: <PR link>\n\nRead the PR and its full diff. Do not use the branch name, commit message, labels, current title, or a shallow summary.\n\nBefore writing, inventory every independently observable behavior in the full diff. A behavior is independent when a user, caller, operator, automation, output, error, exit status, fallback, or side effect can observe it separately. Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet.\n\nFor each behavior, state the trigger or observer, the Before -> After result, the affected surface/caller when shared, and focused proof. Include important preserved behavior and fallback paths when they help a coder rule a regression in or out. Describe outcomes, not line-by-line implementation, and do not hide multiple behaviors under vague umbrella wording.\n\nWrite like the reader is smart but knows nothing about this code. Pretend they asked you to explain it like they are five and feel stupid. If a word needs another sentence to explain it, replace the word — or turn it into a tiny story.\n\nYour job is not a dry API blurb. Your job is an illustrative before/after a person can picture.\n\nGold voice for titles and “What this adds”:\n\nThe theme package has a phone icon somewhere. We need to find it.\n\nBefore: yell “anyone know how to find icons?” and wait for a hand.\n\nAfter: call the finder by its name tag: “icon finder, go.”\n\nThat’s all “operation id” is — the finder’s name tag.\n\nRules for that voice:\n\nStart from a concrete scene (what’s in someone’s hand, what they’re hunting for).\nPrefer Before / After when the change is “how you ask” or “how you look it up.”\nUse picture words: hand it, open, find, check, save, skip, stop, call by name, name tag.\nPrefer spoken results: “found it,” “missing,” “duplicated,” “couldn’t.”\nWhen the diff uses an abstract word (operation id, registry, envelope, adapter, digest, schema), do one of two things:\nDrop it and say what the person does with their hands, or\nKeep it once, then gloss it in the same breath with a name-tag / mailbox / checklist metaphor — like the “finder’s name tag” line above.\nNever leave jargon unexplained. Never write as if the reader already knows the jargon.\nAdd a tiny concrete example in parentheses when a name is abstract (like “the phone icon”).\nFew words. Small words. Clear on first read.\nReturn:\n\nRecommended title\n\nFew words. Small words. Clear on first read.\nSay what you hand it, what it does, and what you get back — or the Before/After of how you ask.\nPrefer picture words and spoken results.\nGood title: “Call the icon finder by its name tag instead of asking around”\nGood title: “Given a theme STP and an asset name, report whether that asset was found, missing, or duplicated”\nBad title: anything that only says operation id / registry / typed envelope / adapter / digest / schema with no picture.\nUse “Add” only if it helps. Do not force it.\nNo vague words like “improve,” “enhance,” or “update.”\nReturn one title only.\nWhy this title fits\n\n1–2 short sentences in the same voice.\nIf needed, one Before / After beat, then what you get back.\nIf this section is needed to decode the title, rewrite the title.\nEvidence\n\nKey files or functions that support the title.\nIf you cannot read the PR or full diff, say so and do not propose a title.\n\nThen write a short, paste-ready PR description.\n\nUse this structure:\n\nWhat this adds\n1–2 short paragraphs in that illustrative voice. Lead with a scene when you can (“The theme package has a phone icon somewhere…”). If the change is a new way to ask, use Before / After. Say what you give it, what it does with its hands, and what you get back. If an abstract machine-word must appear, gloss it immediately (“That’s all X is — …”). Describe the job people can see. Do not describe inner machinery. Mention a check only if it is central to the feature.\n\nWhy\nOne short paragraph. Same plain level. Say who needs this and what goes wrong without it (the “yell and wait for a hand” problem). If this is needed to decode the feature, rewrite “What this adds.”\n\nVerification\nList only proof from the PR, CI, or your own checks.\n\nReported in the PR\n\n…\nChecked by you / CI here\n\n…\nRules:\n\nFew words. Small words. Clear on first read. ELI5 I-am-stupid mark.\nDo not invent behavior, tests, or benefits.\nStrip branch names, hashes, draft notes, agent notes, and merge notes.\nNo vague words like “improve,” “enhance,” or “update.”\nIllustrative first. Abstract labels only if glossed in the same breath.\nUse the recommended title and paste-ready description to run `gh pr edit <PR link> --title ... --body-file ...`, then run `gh pr view <PR link> --json title,body` to confirm the saved title and body. Report the saved result."
     return prompt.replace("<PR link>", url)

package/hooks/git-hooks/test_post_commit.py

@@ -242,6 +242,14 @@ def test_pull_request_reminder_prints_url(
     assert output.startswith("Review this pull request: https://github.com/example/repo/pull/1\n")
     assert "<PR link>" not in output
     assert "Do not use the branch name, commit message, labels, current title" in output
+    assert (
+        "Before writing, inventory every independently observable behavior in the full diff."
+        in output
+        and "Lead with the central behavior for readability, then give every other behavior its own short paragraph or bullet."
+        in output
+        and "For each behavior, state the trigger or observer, the Before -> After result" in output
+        and "OVERRIDE:" not in output
+    )
     assert "gh pr edit https://github.com/example/repo/pull/1" in output
     assert output.rstrip().endswith("Report the saved result.")
 

package/hooks/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|MultiEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -264,7 +264,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_restore.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/bash_post_call_dispatcher.py",
             "timeout": 60
           }
         ]

package/hooks/hooks_constants/bash_post_call_dispatcher_constants.py

@@ -0,0 +1,22 @@
+"""Constants for the Bash PostToolUse dispatcher.
+
+Holds the ordered hosted-hook roster this dispatcher runs after a Bash call
+finishes. Reuses ``BashHostedHookEntry`` and the Bash-only tool-name set from
+``bash_pre_tool_use_dispatcher_constants`` -- the entry shape and the tool-name
+membership question are identical on the PostToolUse side, so this module adds
+no second copy of either.
+"""
+
+from __future__ import annotations
+
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+    ALL_BASH_ONLY_TOOL_NAMES,
+    BashHostedHookEntry,
+)
+
+__all__ = ["ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES"]
+
+ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
+    BashHostedHookEntry("blocking/gh_pr_author_restore.py", ALL_BASH_ONLY_TOOL_NAMES),
+    BashHostedHookEntry("observability/test_failure_recorder.py", ALL_BASH_ONLY_TOOL_NAMES),
+)

package/hooks/hooks_constants/hosted_hook_runner.py

@@ -13,16 +13,27 @@ blocking the tool call.
     run = run_hook_capturing_output("/hooks/blocking/gate.py", '{"tool_name": "Bash"}')
     ok:   run.captured_stdout carries the gate's deny JSON, run.did_crash is False
     flag: run.did_crash is True when the gate raised, run.captured_stdout is ""
+
+``run_dispatcher_main`` holds the entry-point shell a hosted-hook dispatcher's
+own ``main`` needs: read one stdin payload, resolve its tool_name, and hand
+both to the dispatcher's own ``dispatch`` callback. Every dispatcher's
+``main`` reduces to one call into this shared shell, so the read-resolve-exit
+boilerplate lives in one place rather than once per dispatcher.
 """
 
 from __future__ import annotations
 
 import io
+import json
 import runpy
 import sys
+from pathlib import Path
 import traceback
+from collections.abc import Callable
 from dataclasses import dataclass
 
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
 
 @dataclass
 class HostedHookRun:
@@ -71,3 +82,45 @@ def run_hook_capturing_output(hook_script_path: str, payload_text: str) -> Hoste
     finally:
         sys.stdin, sys.stdout, sys.argv = original_stdin, original_stdout, original_argv
     return HostedHookRun(captured_stdout=captured_output.getvalue(), did_crash=did_crash)
+
+
+def resolved_hook_script_path(relative_path: str) -> str:
+    """Resolve a hooks/-relative path to the absolute script path to run.
+
+    ::
+
+        "observability/test_failure_recorder.py" -> <hooks>/observability/...
+
+    The root comes from this module's own location, so every dispatcher
+    resolves against the same directory however deep it sits.
+
+    Args:
+        relative_path: A path relative to the hooks directory.
+
+    Returns:
+        The absolute path of that script.
+    """
+    hooks_root = Path(__file__).resolve().parent.parent
+    return str(hooks_root / relative_path)
+
+
+def run_dispatcher_main(dispatch: Callable[[str, str], None]) -> None:
+    """Read one stdin payload and hand its JSON text and tool_name to dispatch.
+
+    Every hosted-hook dispatcher's own ``main`` reduces to this one call.
+    Exits 0 before ever calling dispatch when stdin is empty, malformed, or
+    names no tool_name string; always exits 0 afterward, since a dispatcher
+    signals its own outcome, if any, through what dispatch itself writes.
+
+    Args:
+        dispatch: The dispatcher's own ``dispatch(payload_text, tool_name)``.
+    """
+    payload_dictionary = read_hook_input_dictionary_from_stdin()
+    if payload_dictionary is None:
+        sys.exit(0)
+    payload_text = json.dumps(payload_dictionary)
+    tool_name = payload_dictionary.get("tool_name", "")
+    if not isinstance(tool_name, str) or not tool_name:
+        sys.exit(0)
+    dispatch(payload_text, tool_name)
+    sys.exit(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/stale_comment_reference_blocker_constants.py

@@ -60,14 +60,13 @@ STALE_COMMENT_DENY_TEMPLATE: str = (
     "The comment above the changed line in {file_path} names "
     "'{orphaned_name}', which this edit removes from the line below. "
     "The comment left in place reads: {contradicted_comment}. "
-    "Update or remove the comment in the same edit."
+    "Remove the comment in the same edit."
 )
 
 STALE_COMMENT_ADDITIONAL_CONTEXT: str = (
     "A standalone comment directly above an edited line describes that "
-    "line. When the edit drops a name the comment carries, rewrite the "
-    "comment to describe the rewritten line, or delete the comment, inside "
-    "the same Edit call."
+    "line. When the edit drops a name the comment carries, remove the "
+    "comment inside the same Edit call."
 )
 
 STALE_COMMENT_SYSTEM_MESSAGE: str = (

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/hooks_constants/test_unused_module_import_constants.py

@@ -9,7 +9,15 @@ _HOOKS_ROOT = Path(__file__).resolve().parent.parent
 if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
-from hooks_constants.unused_module_import_constants import line_suppresses_unused_import_via_noqa
+from hooks_constants.unused_module_import_constants import (
+    UNUSED_IMPORT_GUIDANCE,
+    line_suppresses_unused_import_via_noqa,
+)
+
+
+def test_unused_import_guidance_uses_comment_free_side_effect_remediation() -> None:
+    assert "noqa" not in UNUSED_IMPORT_GUIDANCE
+    assert "importlib.import_module" in UNUSED_IMPORT_GUIDANCE
 
 
 def test_line_suppresses_bare_noqa() -> None:

package/hooks/hooks_constants/unused_module_import_constants.py

@@ -11,7 +11,7 @@ NOQA_DIRECTIVE_PATTERN: re.Pattern[str] = re.compile(
 )
 MAX_UNUSED_IMPORT_ISSUES: int = 25
 UNUSED_IMPORT_GUIDANCE: str = (
-    "remove unused import; if kept for side effects, mark with `# noqa: F401`"
+    "remove unused import; if side effects are required, call importlib.import_module explicitly"
 )
 TYPE_CHECKING_IDENTIFIER: str = "TYPE_CHECKING"
 

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