claude-dev-env 2.4.0 → 2.5.0

package/hooks/blocking/verifier_verdict_minter.py

@@ -1,280 +1,280 @@
-"""SubagentStop hook: mint a commit-gate verdict when code-verifier finishes.
-
-Only this hook writes verdict files — the main session is denied writes to
-the verdict directory, so a session cannot fabricate a passing verdict. The
-SubagentStop payload names the stopping subagent's own transcript
-(``agent_transcript_path``), which sits beside a harness-written
-``agent-<id>.meta.json`` sidecar naming the spawning ``agentType``. The hook
-reads that type from the sidecar, so it resolves identically in interactive,
-background, and worktree-switched sessions; only the harness writes the
-sidecar, so the type it records cannot be forged. When that type is
-``code-verifier``, the hook pulls the verdict block out of the agent's own
-transcript (``agent_transcript_path``), recomputes the live change-surface
-hash for the session repository, and writes the verdict bound to that hash.
-The companion ``verified_commit_gate.py`` (PreToolUse) then allows ``git
-commit`` / ``git push`` only while the work tree still matches the verified
-state.
-
-The verifier's final message must end with a fenced block::
-
-    ```verdict
-    {"all_pass": true, "findings": []}
-    ```
-
-A missing or unparseable block mints nothing, which leaves the gate closed.
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import sys
-from pathlib import Path
-
-blocking_directory = str(Path(__file__).resolve().parent)
-if blocking_directory not in sys.path:
-    sys.path.insert(0, blocking_directory)
-
-from verified_commit_config_bootstrap import (  # noqa: E402
-    register_verified_commit_constants,
-)
-
-register_verified_commit_constants()
-
-from config.verified_commit_constants import (
-    MINTING_AGENT_TYPE,
-    VERDICT_KEY_MANIFEST_SHA256,
-)
-from verification_verdict_store import (
-    branch_surface_manifest,
-    empty_surface_hash,
-    manifest_sha256,
-    resolve_merge_base,
-    resolve_repo_root,
-    write_verdict,
-)
-
-
-def assistant_text_blocks(transcript_path: str) -> list[str]:
-    """Collect every assistant text block from a transcript JSONL file.
-
-    Args:
-        transcript_path: Path to the subagent's transcript.
-
-    Returns:
-        The text of each assistant content block, in transcript order;
-        empty when the file is missing or holds no assistant text.
-    """
-    collected_blocks: list[str] = []
-    try:
-        transcript_lines = (
-            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
-        )
-    except OSError:
-        return collected_blocks
-    for each_line in transcript_lines:
-        try:
-            transcript_entry = json.loads(each_line)
-        except json.JSONDecodeError:
-            continue
-        if not isinstance(transcript_entry, dict):
-            continue
-        if transcript_entry.get("type") != "assistant":
-            continue
-        message_body = transcript_entry.get("message")
-        if not isinstance(message_body, dict):
-            continue
-        content_blocks = message_body.get("content")
-        if not isinstance(content_blocks, list):
-            continue
-        for each_block in content_blocks:
-            if isinstance(each_block, dict) and each_block.get("type") == "text":
-                block_text = each_block.get("text")
-                if isinstance(block_text, str):
-                    collected_blocks.append(block_text)
-    return collected_blocks
-
-
-def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
-    """Extract the final verdict fence from assistant text blocks.
-
-    Args:
-        all_text_blocks: Assistant text blocks in transcript order.
-
-    Returns:
-        The parsed verdict mapping carrying a boolean ``all_pass`` and a
-        list ``findings``, or None when no block holds a wellformed fence.
-    """
-    verdict_fence_pattern = re.compile(r"```verdict\s*\n(.*?)```", re.DOTALL)
-    fence_bodies: list[str] = []
-    for each_block in all_text_blocks:
-        fence_bodies.extend(verdict_fence_pattern.findall(each_block))
-    for each_fence_body in reversed(fence_bodies):
-        try:
-            verdict_record = json.loads(each_fence_body)
-        except json.JSONDecodeError:
-            continue
-        if not isinstance(verdict_record, dict):
-            continue
-        if not isinstance(verdict_record.get("all_pass"), bool):
-            continue
-        if not isinstance(verdict_record.get("findings"), list):
-            continue
-        return verdict_record
-    return None
-
-
-def _agent_type_from_meta_sidecar(agent_transcript_path: str) -> str | None:
-    """Read the spawning agentType from a subagent transcript's sidecar.
-
-    Each subagent transcript ``agent-<id>.jsonl`` sits beside a harness-written
-    ``agent-<id>.meta.json`` naming the spawning ``agentType``. Reading the type
-    from this sidecar binds it to the stopping subagent itself, so it resolves
-    identically in interactive, background, and worktree-switched sessions and
-    needs no parent-transcript scan or flush retry. Only the harness writes this
-    sidecar, so a session cannot forge the type it reports.
-
-    Args:
-        agent_transcript_path: The stopping subagent's own transcript path from
-            the SubagentStop payload.
-
-    Returns:
-        The recorded ``agentType``, or None when the path is empty, the sidecar
-        is absent, unreadable, or unparseable, it does not hold a JSON object,
-        or it names no string ``agentType``.
-    """
-    if not agent_transcript_path:
-        return None
-    transcript_file = Path(agent_transcript_path)
-    sidecar_file = transcript_file.with_name(f"{transcript_file.stem}.meta.json")
-    try:
-        sidecar_record = json.loads(sidecar_file.read_text(encoding="utf-8"))
-    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
-        return None
-    if not isinstance(sidecar_record, dict):
-        return None
-    recorded_type = sidecar_record.get("agentType")
-    return recorded_type if isinstance(recorded_type, str) else None
-
-
-def resolved_subagent_type(subagent_stop_payload: dict) -> str | None:
-    """Recover the spawning agent type for a SubagentStop payload.
-
-    The stopping subagent's own transcript (``agent_transcript_path``) sits
-    beside a harness-written ``agent-<id>.meta.json`` sidecar naming its
-    ``agentType``. The type comes solely from that sidecar, which only the
-    harness writes — the main session can neither write the sidecar nor forge
-    the agentType it records. A verdict fence in the transcript is never used to
-    infer the type, because the main session controls the prompt of any
-    Agent-tool subagent it spawns and could instruct one to print such a fence.
-
-    Args:
-        subagent_stop_payload: The SubagentStop hook payload.
-
-    Returns:
-        The agent type the sidecar records, or None when the
-        ``agent_transcript_path`` is empty, the sidecar is absent, unreadable,
-        or unparseable, it does not hold a JSON object, or it names no string
-        ``agentType``.
-    """
-    return _agent_type_from_meta_sidecar(
-        subagent_stop_payload.get("agent_transcript_path", "")
-    )
-
-
-def _attested_or_recomputed_hash(verdict_record: dict, repo_root: str) -> str | None:
-    """Choose the surface hash the minted verdict binds to.
-
-    A code-verifier that verifies a work tree other than the stop event's cwd
-    attests the surface it checked by emitting ``manifest_sha256`` in its
-    verdict fence (computed against the verified work tree via the
-    ``--manifest-hash`` CLI). Binding the minted verdict to that attested hash
-    keeps the verdict tied to the code actually verified rather than the
-    subagent's cwd, so a verdict earned for one work tree clears a commit in a
-    sibling work tree of the same surface. When the fence attests no hash, the
-    minter recomputes one from the cwd work tree, which is correct whenever the
-    verifier ran in the work tree it verified.
-
-    Returns None (mints nothing) in two empty-surface cases:
-
-    - The attested hash equals ``empty_surface_hash()`` — the verifier called
-      the store CLI on a wrong (empty) work tree and the hash it got back
-      represents nothing.
-    - The recompute branch produces an empty manifest — the cwd work tree also
-      has no changed or untracked files versus the merge base.
-
-    Args:
-        verdict_record: The parsed verdict fence from the verifier transcript.
-        repo_root: The work-tree root resolved from the stop event's cwd, used
-            for the recompute fallback.
-
-    Returns:
-        The attested ``manifest_sha256`` when the fence carries a non-empty
-        string one that is not the empty-surface sentinel; the cwd work tree's
-        recomputed surface hash when the fence attests nothing and the surface
-        is non-empty; or None when the attested hash is the empty-surface
-        sentinel, the surface manifest is empty, or no upstream base resolves.
-    """
-    attested_manifest_sha256 = verdict_record.get(VERDICT_KEY_MANIFEST_SHA256)
-    if isinstance(attested_manifest_sha256, str) and attested_manifest_sha256:
-        if attested_manifest_sha256 == empty_surface_hash():
-            return None
-        return attested_manifest_sha256
-    merge_base_sha = resolve_merge_base(repo_root)
-    if merge_base_sha is None:
-        return None
-    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
-    if not surface_manifest_text:
-        return None
-    return manifest_sha256(surface_manifest_text)
-
-
-def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
-    """Mint a verdict file for a code-verifier stop event.
-
-    Args:
-        subagent_stop_payload: The SubagentStop hook payload.
-
-    Returns:
-        The verdict file path when minted; None when the payload is not a
-        code-verifier stop, the transcript holds no verdict, the cwd is not a
-        work tree, or — for a verdict that attests no ``manifest_sha256`` of
-        its own — that work tree has no upstream base to recompute the surface
-        hash from.
-    """
-    if resolved_subagent_type(subagent_stop_payload) != MINTING_AGENT_TYPE:
-        return None
-    agent_transcript_path = subagent_stop_payload.get("agent_transcript_path", "")
-    if not agent_transcript_path:
-        return None
-    verdict_record = last_verdict_in_blocks(assistant_text_blocks(agent_transcript_path))
-    if verdict_record is None:
-        return None
-    repo_root = resolve_repo_root(subagent_stop_payload.get("cwd", "."))
-    if repo_root is None:
-        return None
-    bound_manifest_sha256 = _attested_or_recomputed_hash(verdict_record, repo_root)
-    if bound_manifest_sha256 is None:
-        return None
-    return write_verdict(
-        repo_root,
-        bound_manifest_sha256,
-        verdict_record["all_pass"],
-        verdict_record["findings"],
-        str(subagent_stop_payload.get("agent_id", "")),
-    )
-
-
-def main() -> None:
-    """Read the SubagentStop payload and mint a verdict when one applies."""
-    try:
-        subagent_stop_payload = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return
-    if not isinstance(subagent_stop_payload, dict):
-        return
-    mint_for_payload(subagent_stop_payload)
-
-
-if __name__ == "__main__":
-    main()
+"""SubagentStop hook: mint a commit-gate verdict when code-verifier finishes.
+
+Only this hook writes verdict files — the main session is denied writes to
+the verdict directory, so a session cannot fabricate a passing verdict. The
+SubagentStop payload names the stopping subagent's own transcript
+(``agent_transcript_path``), which sits beside a harness-written
+``agent-<id>.meta.json`` sidecar naming the spawning ``agentType``. The hook
+reads that type from the sidecar, so it resolves identically in interactive,
+background, and worktree-switched sessions; only the harness writes the
+sidecar, so the type it records cannot be forged. When that type is
+``code-verifier``, the hook pulls the verdict block out of the agent's own
+transcript (``agent_transcript_path``), recomputes the live change-surface
+hash for the session repository, and writes the verdict bound to that hash.
+The companion ``verified_commit_gate.py`` (PreToolUse) then allows ``git
+commit`` / ``git push`` only while the work tree still matches the verified
+state.
+
+The verifier's final message must end with a fenced block::
+
+    ```verdict
+    {"all_pass": true, "findings": []}
+    ```
+
+A missing or unparseable block mints nothing, which leaves the gate closed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from verified_commit_config_bootstrap import (  # noqa: E402
+    register_verified_commit_constants,
+)
+
+register_verified_commit_constants()
+
+from config.verified_commit_constants import (
+    MINTING_AGENT_TYPE,
+    VERDICT_KEY_MANIFEST_SHA256,
+)
+from verification_verdict_store import (
+    branch_surface_manifest,
+    empty_surface_hash,
+    manifest_sha256,
+    resolve_merge_base,
+    resolve_repo_root,
+    write_verdict,
+)
+
+
+def assistant_text_blocks(transcript_path: str) -> list[str]:
+    """Collect every assistant text block from a transcript JSONL file.
+
+    Args:
+        transcript_path: Path to the subagent's transcript.
+
+    Returns:
+        The text of each assistant content block, in transcript order;
+        empty when the file is missing or holds no assistant text.
+    """
+    collected_blocks: list[str] = []
+    try:
+        transcript_lines = (
+            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    except OSError:
+        return collected_blocks
+    for each_line in transcript_lines:
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(transcript_entry, dict):
+            continue
+        if transcript_entry.get("type") != "assistant":
+            continue
+        message_body = transcript_entry.get("message")
+        if not isinstance(message_body, dict):
+            continue
+        content_blocks = message_body.get("content")
+        if not isinstance(content_blocks, list):
+            continue
+        for each_block in content_blocks:
+            if isinstance(each_block, dict) and each_block.get("type") == "text":
+                block_text = each_block.get("text")
+                if isinstance(block_text, str):
+                    collected_blocks.append(block_text)
+    return collected_blocks
+
+
+def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
+    """Extract the final verdict fence from assistant text blocks.
+
+    Args:
+        all_text_blocks: Assistant text blocks in transcript order.
+
+    Returns:
+        The parsed verdict mapping carrying a boolean ``all_pass`` and a
+        list ``findings``, or None when no block holds a wellformed fence.
+    """
+    verdict_fence_pattern = re.compile(r"```verdict\s*\n(.*?)```", re.DOTALL)
+    fence_bodies: list[str] = []
+    for each_block in all_text_blocks:
+        fence_bodies.extend(verdict_fence_pattern.findall(each_block))
+    for each_fence_body in reversed(fence_bodies):
+        try:
+            verdict_record = json.loads(each_fence_body)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(verdict_record, dict):
+            continue
+        if not isinstance(verdict_record.get("all_pass"), bool):
+            continue
+        if not isinstance(verdict_record.get("findings"), list):
+            continue
+        return verdict_record
+    return None
+
+
+def _agent_type_from_meta_sidecar(agent_transcript_path: str) -> str | None:
+    """Read the spawning agentType from a subagent transcript's sidecar.
+
+    Each subagent transcript ``agent-<id>.jsonl`` sits beside a harness-written
+    ``agent-<id>.meta.json`` naming the spawning ``agentType``. Reading the type
+    from this sidecar binds it to the stopping subagent itself, so it resolves
+    identically in interactive, background, and worktree-switched sessions and
+    needs no parent-transcript scan or flush retry. Only the harness writes this
+    sidecar, so a session cannot forge the type it reports.
+
+    Args:
+        agent_transcript_path: The stopping subagent's own transcript path from
+            the SubagentStop payload.
+
+    Returns:
+        The recorded ``agentType``, or None when the path is empty, the sidecar
+        is absent, unreadable, or unparseable, it does not hold a JSON object,
+        or it names no string ``agentType``.
+    """
+    if not agent_transcript_path:
+        return None
+    transcript_file = Path(agent_transcript_path)
+    sidecar_file = transcript_file.with_name(f"{transcript_file.stem}.meta.json")
+    try:
+        sidecar_record = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(sidecar_record, dict):
+        return None
+    recorded_type = sidecar_record.get("agentType")
+    return recorded_type if isinstance(recorded_type, str) else None
+
+
+def resolved_subagent_type(subagent_stop_payload: dict) -> str | None:
+    """Recover the spawning agent type for a SubagentStop payload.
+
+    The stopping subagent's own transcript (``agent_transcript_path``) sits
+    beside a harness-written ``agent-<id>.meta.json`` sidecar naming its
+    ``agentType``. The type comes solely from that sidecar, which only the
+    harness writes — the main session can neither write the sidecar nor forge
+    the agentType it records. A verdict fence in the transcript is never used to
+    infer the type, because the main session controls the prompt of any
+    Agent-tool subagent it spawns and could instruct one to print such a fence.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The agent type the sidecar records, or None when the
+        ``agent_transcript_path`` is empty, the sidecar is absent, unreadable,
+        or unparseable, it does not hold a JSON object, or it names no string
+        ``agentType``.
+    """
+    return _agent_type_from_meta_sidecar(
+        subagent_stop_payload.get("agent_transcript_path", "")
+    )
+
+
+def _attested_or_recomputed_hash(verdict_record: dict, repo_root: str) -> str | None:
+    """Choose the surface hash the minted verdict binds to.
+
+    A code-verifier that verifies a work tree other than the stop event's cwd
+    attests the surface it checked by emitting ``manifest_sha256`` in its
+    verdict fence (computed against the verified work tree via the
+    ``--manifest-hash`` CLI). Binding the minted verdict to that attested hash
+    keeps the verdict tied to the code actually verified rather than the
+    subagent's cwd, so a verdict earned for one work tree clears a commit in a
+    sibling work tree of the same surface. When the fence attests no hash, the
+    minter recomputes one from the cwd work tree, which is correct whenever the
+    verifier ran in the work tree it verified.
+
+    Returns None (mints nothing) in two empty-surface cases:
+
+    - The attested hash equals ``empty_surface_hash()`` — the verifier called
+      the store CLI on a wrong (empty) work tree and the hash it got back
+      represents nothing.
+    - The recompute branch produces an empty manifest — the cwd work tree also
+      has no changed or untracked files versus the merge base.
+
+    Args:
+        verdict_record: The parsed verdict fence from the verifier transcript.
+        repo_root: The work-tree root resolved from the stop event's cwd, used
+            for the recompute fallback.
+
+    Returns:
+        The attested ``manifest_sha256`` when the fence carries a non-empty
+        string one that is not the empty-surface sentinel; the cwd work tree's
+        recomputed surface hash when the fence attests nothing and the surface
+        is non-empty; or None when the attested hash is the empty-surface
+        sentinel, the surface manifest is empty, or no upstream base resolves.
+    """
+    attested_manifest_sha256 = verdict_record.get(VERDICT_KEY_MANIFEST_SHA256)
+    if isinstance(attested_manifest_sha256, str) and attested_manifest_sha256:
+        if attested_manifest_sha256 == empty_surface_hash():
+            return None
+        return attested_manifest_sha256
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if not surface_manifest_text:
+        return None
+    return manifest_sha256(surface_manifest_text)
+
+
+def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
+    """Mint a verdict file for a code-verifier stop event.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The verdict file path when minted; None when the payload is not a
+        code-verifier stop, the transcript holds no verdict, the cwd is not a
+        work tree, or — for a verdict that attests no ``manifest_sha256`` of
+        its own — that work tree has no upstream base to recompute the surface
+        hash from.
+    """
+    if resolved_subagent_type(subagent_stop_payload) != MINTING_AGENT_TYPE:
+        return None
+    agent_transcript_path = subagent_stop_payload.get("agent_transcript_path", "")
+    if not agent_transcript_path:
+        return None
+    verdict_record = last_verdict_in_blocks(assistant_text_blocks(agent_transcript_path))
+    if verdict_record is None:
+        return None
+    repo_root = resolve_repo_root(subagent_stop_payload.get("cwd", "."))
+    if repo_root is None:
+        return None
+    bound_manifest_sha256 = _attested_or_recomputed_hash(verdict_record, repo_root)
+    if bound_manifest_sha256 is None:
+        return None
+    return write_verdict(
+        repo_root,
+        bound_manifest_sha256,
+        verdict_record["all_pass"],
+        verdict_record["findings"],
+        str(subagent_stop_payload.get("agent_id", "")),
+    )
+
+
+def main() -> None:
+    """Read the SubagentStop payload and mint a verdict when one applies."""
+    try:
+        subagent_stop_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(subagent_stop_payload, dict):
+        return
+    mint_for_payload(subagent_stop_payload)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/git-hooks/test_pre_push.py

@@ -542,3 +542,28 @@ def test_main_allows_deletion_push_even_when_code_review_gate_would_block(
     exit_code = pre_push.main()
 
     assert exit_code == 0
+
+
+def test_main_allows_when_code_review_enforcement_flag_is_off(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Native pre-push honors the real gate with enforcement off.
+
+    Points at the production push gate (not a reason stub). With the shipped
+    default `CODE_REVIEW_ENFORCEMENT_ENABLED = False`, the gate returns no
+    deny reason and the backstop allows the push — one path covering flag,
+    real gate load, and pre-push exit together.
+    """
+    _write_passing_code_rules_gate(tmp_path, monkeypatch)
+    real_gate_path = (
+        Path(__file__).resolve().parent.parent
+        / "blocking"
+        / "code_review_push_gate.py"
+    )
+    assert real_gate_path.is_file()
+    monkeypatch.setenv("CODE_REVIEW_PUSH_GATE_PATH", str(real_gate_path))
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0

package/hooks/hooks.json

@@ -102,6 +102,16 @@
           }
         ]
       },
+      {
+        "matcher": "ScheduleWakeup|CronCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/orchestrator_refresh_reschedule_gate.py",
+            "timeout": 15
+          }
+        ]
+      },
       {
         "matcher": "Skill",
         "hooks": [

package/hooks/hooks_constants/CLAUDE.md

@@ -64,6 +64,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
 | `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
 | `reviewer_spawn_gate_constants.py` | Bash tool name, the sentinel marker, the Copilot and Bugbot trigger markers, the availability-script relative path and override env-var name, and the deny-message template for the reviewer-spawn gate |
+| `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
 | `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
 | `sensitive_file_protector_constants.py` | Sensitive filename patterns, the committed-template suffixes that earn an exemption, the write/edit tool names, and the deny decision and message template for `sensitive_file_protector` |
 | `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
@@ -90,6 +91,6 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 - Most files in this package are pure constants modules — no side effects, no I/O.
 - Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
 - Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
-- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they are shared across many hooks.
+- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they hold logic shared across hook surfaces.
 - `local_identity.py` is a loader: it reads the environment or `~/.claude/local-identity.json` (its path overridable via `CLAUDE_LOCAL_IDENTITY_PATH`) to resolve private NAS values (with committed placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`).