claude-dev-env 1.73.0 → 1.74.0

package/hooks/blocking/session_handoff_blocker.py

@@ -18,6 +18,7 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_CONTEXT_REASSURANCE_NOTICE  # noqa: E402
 from hooks_constants.session_handoff_blocker_constants import (  # noqa: E402
     FIRST_PERSON_SUBJECT_PATTERN,
@@ -169,19 +170,24 @@ def main() -> None:
     if not find_session_handoff_proposal(assistant_message):
         sys.exit(0)
 
+    block_reason = (
+        "LONG-HORIZON-AUTONOMY GUARDRAIL: You have ample context remaining. Do not "
+        "stop, summarize, or suggest a new session on account of context limits. "
+        "Continue the work.\n\n"
+        "Re-output your response continuing the task without the handoff suggestion, "
+        "per the long-horizon-autonomy rule."
+    )
     block_response = {
         "decision": "block",
-        "reason": (
-            "LONG-HORIZON-AUTONOMY GUARDRAIL: You have ample context remaining. Do not "
-            "stop, summarize, or suggest a new session on account of context limits. "
-            "Continue the work.\n\n"
-            "Re-output your response continuing the task without the handoff suggestion, "
-            "per the long-horizon-autonomy rule."
-        ),
+        "reason": block_reason,
         "systemMessage": USER_FACING_CONTEXT_REASSURANCE_NOTICE,
         "suppressOutput": True,
     }
-
+    log_hook_block(
+        calling_hook_name="session_handoff_blocker.py",
+        hook_event="Stop",
+        block_reason=block_reason,
+    )
     print(json.dumps(block_response))
     sys.exit(0)
 

package/hooks/blocking/state_description_blocker.py

@@ -17,6 +17,7 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.state_description_blocker_constants import (  # noqa: E402
     ALL_BLOCK_COMMENT_EXTENSIONS,
     ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
@@ -235,6 +236,11 @@ def build_deny_payload(deny_reason: str) -> dict[str, object]:
     Returns:
         The deny payload dictionary the hook serializes to stdout.
     """
+    log_hook_block(
+        calling_hook_name="state_description_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
     return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",

package/hooks/blocking/subprocess_budget_completeness.py

@@ -44,6 +44,7 @@ if _hooks_dir not in sys.path:
 
 from code_rules_shared import is_test_file  # noqa: E402
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )
@@ -360,15 +361,20 @@ def main() -> None:
         sys.exit(0)
 
     function_name, omitted_values = undercounted_budget
+    deny_reason = format_block_message(file_path, function_name, omitted_values)
+    log_hook_block(
+        calling_hook_name="subprocess_budget_completeness.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+        offending_input_preview=file_path,
+    )
     print(
         json.dumps(
             {
                 "hookSpecificOutput": {
                     "hookEventName": "PreToolUse",
                     "permissionDecision": "deny",
-                    "permissionDecisionReason": format_block_message(
-                        file_path, function_name, omitted_values
-                    ),
+                    "permissionDecisionReason": deny_reason,
                 }
             }
         )

package/hooks/blocking/tdd_enforcer.py

@@ -24,6 +24,7 @@ if _blocking_directory_path_string not in sys.path:
 
 from code_rules_shared import is_ephemeral_script_path  # noqa: E402
 
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.messages import USER_FACING_TDD_NOTICE  # noqa: E402
 
 PRODUCTION_EXTENSIONS = {'.py', '.ts', '.tsx', '.js', '.jsx'}
@@ -538,6 +539,11 @@ def emit_deny(reason: str) -> None:
         "suppressOutput": True,
         "systemMessage": USER_FACING_TDD_NOTICE,
     }
+    log_hook_block(
+        calling_hook_name="tdd_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=reason,
+    )
     print(json.dumps(deny_payload))
 
 

package/hooks/blocking/test_code_rules_enforcer_docstring_returns_plural_cardinality.py

@@ -0,0 +1,207 @@
+"""Tests for check_docstring_returns_plural_cardinality — O6 plural-stop drift.
+
+A function returns a dict literal whose keys carry prefix families, and its
+Returns clause names one such family with a plural noun ("the sheen stops")
+while only one key in that family exists ("sheen_mid"). The plural prose claims
+two or more entries the dict no longer holds. This is the deterministic
+single-key slice of Category O6 docstring-prose-vs-implementation drift, the
+shape that appears when a producer removes the second key in a family but leaves
+the plural prose untouched.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_returns_plural_cardinality(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_returns_plural_cardinality(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/phone_handset.py"
+TEST_FILE_PATH = "/project/src/test_phone_handset.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_single_sheen_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stops, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "body_shadow": derive_shadow(colors.body),\n'
+        '        "body_inner_shadow": derive_inner(colors.body),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        '        "depth_mid": colors.depth,\n'
+        "    }\n"
+    )
+
+
+def _singular_sheen_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stop, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "body_shadow": derive_shadow(colors.body),\n'
+        '        "body_inner_shadow": derive_inner(colors.body),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        '        "depth_mid": colors.depth,\n'
+        "    }\n"
+    )
+
+
+def _plural_family_with_two_keys_function() -> str:
+    return (
+        "def _palette_substitutions(colors: PhoneHandsetColors) -> dict[str, str]:\n"
+        '    """Derive every SVG color field from the three theme hero colors.\n'
+        "\n"
+        "    Returns:\n"
+        "        The color substitution fields the SVG template fills: the body form\n"
+        "        stops (highlight, mid, shadow, inner-shadow), the sheen stops, the rim\n"
+        "        highlight, the depth, and the specular core that lights the gloss.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_highlight": derive_highlight(colors.body),\n'
+        '        "body_mid": colors.body,\n'
+        '        "sheen_highlight": derive_sheen_highlight(colors.sheen),\n'
+        '        "sheen_mid": colors.sheen,\n'
+        '        "rim_highlight": derive_rim(colors.sheen),\n'
+        '        "specular_core": derive_specular(colors.sheen),\n'
+        "    }\n"
+    )
+
+
+def test_should_flag_plural_stops_with_single_family_key() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("sheen" in each for each in issues), (
+        f"The plural 'sheen stops' against a single sheen_mid key must be flagged, got: {issues!r}"
+    )
+
+
+def test_should_report_category_o6_in_the_message() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert any("O6" in each for each in issues), (
+        f"Expected the Category O6 label in the message, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_singular_noun() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _singular_sheen_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A singular 'sheen stop' matching one key must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_plural_family_with_two_keys() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _plural_family_with_two_keys_function(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], (
+        f"A plural 'sheen stops' matching two sheen_ keys must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_family_absent_from_dict() -> None:
+    source = (
+        "def build() -> dict[str, str]:\n"
+        '    """Build the fields.\n'
+        "\n"
+        "    Returns:\n"
+        "        The body stops and the sheen stops the template fills.\n"
+        '    """\n'
+        "    return {\n"
+        '        "body_mid": "a",\n'
+        '        "rim_highlight": "b",\n'
+        "    }\n"
+    )
+    issues = check_docstring_returns_plural_cardinality(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A plural family with no matching dict keys must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_not_flag_when_no_returns_section() -> None:
+    source = (
+        "def build() -> dict[str, str]:\n"
+        '    """Build the sheen stops without a Returns section."""\n'
+        "    return {\n"
+        '        "sheen_mid": "a",\n'
+        "    }\n"
+    )
+    issues = check_docstring_returns_plural_cardinality(source, PRODUCTION_FILE_PATH)
+    assert issues == [], (
+        f"A plural noun outside a Returns section must not be flagged, got: {issues!r}"
+    )
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_docstring_returns_plural_cardinality(
+        _drifted_single_sheen_function(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_docstring_returns_plural_cardinality("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_plural_cardinality_drift() -> None:
+    issues = validate_content(
+        _drifted_single_sheen_function(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [each for each in issues if "sheen" in each and "O6" in each]
+    assert matching_issues, (
+        f"Expected validate_content to surface the O6 plural-cardinality drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_docstring_unguarded_payload.py

@@ -0,0 +1,188 @@
+"""Tests for check_docstring_unguarded_malformed_payload_claim — Category O6 drift.
+
+A function docstring that promises "a malformed payload resolves to None" asserts
+the body catches a bad payload and turns it into a None return. The claim drifts
+when the value construction that dereferences payload fields (``payload["key"]``,
+``float(payload["key"])``) sits OUTSIDE the try/except whose handler returns None:
+a present-but-malformed payload raises KeyError or TypeError from that unguarded
+dereference and propagates rather than resolving to None. This is the deterministic
+slice of Category O6 (docstring prose vs implementation drift) for an
+exception-guard claim.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_unguarded_malformed_payload_claim(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_unguarded_malformed_payload_claim(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/shared/human_actions.py"
+TEST_FILE_PATH = "/project/shared/test_human_actions.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+_UNGUARDED_DEREFERENCE_BODY = (
+    "def read_metrics(self, selector: str) -> object:\n"
+    '    """Read the container geometry over CDP, or None on failure.\n'
+    "\n"
+    "    A missing element, a CDP error, or a malformed payload resolves to None\n"
+    "    so the caller skips the drag.\n"
+    '    """\n'
+    "    try:\n"
+    "        evaluate_payload = self.cdp.run(selector)\n"
+    "        parsed_metrics = json.loads(evaluate_payload)\n"
+    "    except (KeyError, TypeError, ValueError):\n"
+    "        return None\n"
+    '    if not parsed_metrics.get("found"):\n'
+    "        return None\n"
+    "    return Metrics(\n"
+    '        client_width=float(parsed_metrics["client_width"]),\n'
+    '        client_height=float(parsed_metrics["client_height"]),\n'
+    "    )\n"
+)
+
+
+def test_flags_dereference_outside_the_guarded_block() -> None:
+    issues = check_docstring_unguarded_malformed_payload_claim(
+        _UNGUARDED_DEREFERENCE_BODY, PRODUCTION_FILE_PATH
+    )
+    assert len(issues) == 1
+    assert "read_metrics" in issues[0]
+
+
+def test_passes_when_dereference_sits_inside_the_guarded_block() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A missing element, a CDP error, or a malformed payload resolves to None\n"
+        "    so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        evaluate_payload = self.cdp.run(selector)\n"
+        "        parsed_metrics = json.loads(evaluate_payload)\n"
+        '        if not parsed_metrics.get("found"):\n'
+        "            return None\n"
+        "        return Metrics(\n"
+        '            client_width=float(parsed_metrics["client_width"]),\n'
+        '            client_height=float(parsed_metrics["client_height"]),\n'
+        "        )\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_docstring_makes_no_malformed_payload_claim() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure."""\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        "    return Metrics(\n"
+        '        client_width=float(parsed_metrics["client_width"]),\n'
+        "    )\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_no_subscript_dereference_follows_the_guard() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A malformed payload resolves to None so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        '    return parsed_metrics.get("found")\n'
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_post_guard_subscript_dereferences_an_unrelated_name() -> None:
+    content = (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the geometry over CDP, or None on failure.\n'
+        "\n"
+        "    A malformed payload resolves to None so the caller skips the drag.\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        '        width = float(parsed_metrics["client_width"])\n'
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        "    fallback = cache[selector]\n"
+        "    return Metrics(client_width=width, fallback=fallback)\n"
+    )
+    assert check_docstring_unguarded_malformed_payload_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def _unguarded_body_with_claim(claim_sentence: str) -> str:
+    return (
+        "def read_metrics(self, selector: str) -> object:\n"
+        '    """Read the container geometry over CDP, or None on failure.\n'
+        "\n"
+        f"    {claim_sentence}\n"
+        '    """\n'
+        "    try:\n"
+        "        parsed_metrics = json.loads(self.cdp.run(selector))\n"
+        "    except (KeyError, TypeError, ValueError):\n"
+        "        return None\n"
+        '    return float(parsed_metrics["client_width"])\n'
+    )
+
+
+def test_article_prefixed_claim_phrasings_still_flag_via_articleless_substring() -> None:
+    all_article_prefixed_claims = (
+        "A malformed payload resolves to None so the caller skips the drag.",
+        "A bad payload resolves to None so the caller skips the drag.",
+        "An invalid payload resolves to None so the caller skips the drag.",
+        "A malformed payload yields None so the caller skips the drag.",
+    )
+    for each_claim in all_article_prefixed_claims:
+        issues = check_docstring_unguarded_malformed_payload_claim(
+            _unguarded_body_with_claim(each_claim), PRODUCTION_FILE_PATH
+        )
+        assert len(issues) == 1
+        assert "read_metrics" in issues[0]
+
+
+def test_test_files_are_exempt() -> None:
+    assert (
+        check_docstring_unguarded_malformed_payload_claim(
+            _UNGUARDED_DEREFERENCE_BODY, TEST_FILE_PATH
+        )
+        == []
+    )
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    assert (
+        check_docstring_unguarded_malformed_payload_claim(
+            _UNGUARDED_DEREFERENCE_BODY, HOOK_INFRASTRUCTURE_PATH
+        )
+        == []
+    )

package/hooks/blocking/test_code_verifier_spawn_preflight_gate.py

@@ -8,6 +8,7 @@ test_precommit_code_rules_gate.py lines 1-70.
 """
 
 import json
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -454,3 +455,47 @@ def test_conflict_and_violation_single_deny_names_both(tmp_path: Path) -> None:
     assert "shared.py" in reason
     assert "CODE_RULES violations on changed lines:" in reason
     assert "violator.py" in reason
+
+
+def test_hook_imports_real_config_when_parent_holds_shadowing_config(
+    tmp_path: Path,
+) -> None:
+    real_hooks_directory = HOOK_PATH.parent.parent
+    real_package_directory = real_hooks_directory.parent
+
+    staged_package_directory = tmp_path / "claude-dev-env"
+    shutil.copytree(
+        real_hooks_directory,
+        staged_package_directory / "hooks",
+    )
+    shutil.copytree(
+        real_package_directory / "_shared",
+        staged_package_directory / "_shared",
+    )
+
+    shadowing_config_directory = staged_package_directory / "hooks" / "config"
+    shadowing_config_directory.mkdir(parents=True, exist_ok=True)
+    (shadowing_config_directory / "__init__.py").write_text("", encoding="utf-8")
+    (shadowing_config_directory / "unrelated_constants.py").write_text(
+        "UNRELATED_VALUE = 1\n", encoding="utf-8"
+    )
+
+    staged_hook = (
+        staged_package_directory
+        / "hooks"
+        / "blocking"
+        / "code_verifier_spawn_preflight_gate.py"
+    )
+    payload = write_agent_payload("general-purpose", "unrelated work", tmp_path)
+    completed = subprocess.run(
+        [sys.executable, str(staged_hook)],
+        check=False,
+        input=payload,
+        capture_output=True,
+        text=True,
+        cwd=str(tmp_path),
+        timeout=120,
+    )
+
+    assert "ModuleNotFoundError" not in completed.stderr
+    assert completed.returncode == 0