claude-dev-env 2.29.0 → 2.30.1

package/hooks/blocking/shell_substitution_blocker.py

@@ -24,13 +24,28 @@ are treated as literal only when the count of preceding backslashes is odd;
 an even count (including zero) means the backtick is a live substitution.
 
 Bash arithmetic expansion ``$((...))`` is explicitly NOT blocked: it does not
-spawn a subshell and does not defeat the allowlist matcher, so the
-``$(`` pattern uses a negative lookahead to skip the ``$((`` case.
+spawn a subshell and does not defeat the allowlist matcher. Telling it apart
+from a disguised command substitution takes more than counting two open
+parens, because bash itself falls back from arithmetic to command
+substitution when the expansion body does not close as arithmetic. Observed
+against real bash:
+
+    echo $((1 + 2))            prints 3            (arithmetic; not blocked)
+    echo $((cd /tmp) && pwd)   prints the new cwd   (command substitution; blocked)
+    echo $((1+2) )             runs "1+2" as a command, rc=0, no output
+                                                     (command substitution; blocked)
+
+Bash's own rule is the terminator: walk forward from ``$((`` tracking paren
+depth; when depth returns to zero on a closer immediately preceded by
+another ``)`` (an ``))`` pair), the expansion is arithmetic and passes. When
+the closer that brings depth to zero is a lone ``)``, bash has fallen back to
+running a parenthesized command inside the substitution, so it is blocked.
+This hook applies that walk, tracking paren depth from the opening ``$((``.
 
 False positives are still possible when the user is intentionally writing
 shell-script content (for example, authoring a .sh file via heredoc) and the
 substitution is literal payload rather than something to execute. In that
-case, write via the Write tool instead of a Bash heredoc.
+case, author the file with the Write tool, not a Bash heredoc.
 """
 
 from __future__ import annotations
@@ -39,34 +54,95 @@ import json
 import sys
 from pathlib import Path
 
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
-from hooks_constants.shell_substitution_blocker_constants import (  # noqa: E402
-    BASH_TOOL_NAME,
-    COMMAND_KEY,
-    CORRECTIVE_MESSAGE,
-    DENY_DECISION,
-    DOLLAR_PAREN_PATTERN,
-    EVEN_BACKSLASH_BACKTICK_PATTERN,
-    HOOK_EVENT_NAME,
-    HOOK_EVENT_NAME_KEY,
-    HOOK_SPECIFIC_OUTPUT_KEY,
-    PERMISSION_DECISION_KEY,
-    PERMISSION_DECISION_REASON_KEY,
-    PROCESS_SUBSTITUTION_PATTERN,
-    SINGLE_QUOTED_RUN_PATTERN,
-    STRIPPED_RUN_REPLACEMENT,
-    TOOL_INPUT_KEY,
-    TOOL_NAME_KEY,
-)
+try:
+    from hooks_constants.shell_substitution_blocker_constants import (
+        BASH_TOOL_NAME,
+        CLOSE_PAREN_CHARACTER,
+        COMMAND_KEY,
+        CORRECTIVE_MESSAGE,
+        DENY_DECISION,
+        DOLLAR_PAREN_PATTERN,
+        EVEN_BACKSLASH_BACKTICK_PATTERN,
+        HOOK_EVENT_NAME,
+        HOOK_EVENT_NAME_KEY,
+        HOOK_SPECIFIC_OUTPUT_KEY,
+        OPEN_PAREN_CHARACTER,
+        PAREN_DEPTH_AFTER_DOUBLE_OPEN,
+        PERMISSION_DECISION_KEY,
+        PERMISSION_DECISION_REASON_KEY,
+        PROCESS_SUBSTITUTION_PATTERN,
+        SINGLE_QUOTED_RUN_PATTERN,
+        STRIPPED_RUN_REPLACEMENT,
+        TOOL_INPUT_KEY,
+        TOOL_NAME_KEY,
+    )
+except ModuleNotFoundError:
+    _hooks_dir = str(Path(__file__).resolve().parent.parent)
+    if _hooks_dir not in sys.path:
+        sys.path.insert(0, _hooks_dir)
+    from hooks_constants.shell_substitution_blocker_constants import (
+        BASH_TOOL_NAME,
+        CLOSE_PAREN_CHARACTER,
+        COMMAND_KEY,
+        CORRECTIVE_MESSAGE,
+        DENY_DECISION,
+        DOLLAR_PAREN_PATTERN,
+        EVEN_BACKSLASH_BACKTICK_PATTERN,
+        HOOK_EVENT_NAME,
+        HOOK_EVENT_NAME_KEY,
+        HOOK_SPECIFIC_OUTPUT_KEY,
+        OPEN_PAREN_CHARACTER,
+        PAREN_DEPTH_AFTER_DOUBLE_OPEN,
+        PERMISSION_DECISION_KEY,
+        PERMISSION_DECISION_REASON_KEY,
+        PROCESS_SUBSTITUTION_PATTERN,
+        SINGLE_QUOTED_RUN_PATTERN,
+        STRIPPED_RUN_REPLACEMENT,
+        TOOL_INPUT_KEY,
+        TOOL_NAME_KEY,
+    )
 
 
 def _strip_single_quoted_runs(command: str) -> str:
     return SINGLE_QUOTED_RUN_PATTERN.sub(STRIPPED_RUN_REPLACEMENT, command)
 
 
+def _closes_as_arithmetic_expansion(command: str, scan_start_index: int) -> bool:
+    """Return True when a ``$((`` expansion closes on an ``))`` pair.
+
+    See the module docstring for the real-bash evidence behind this rule.
+    """
+    paren_depth = PAREN_DEPTH_AFTER_DOUBLE_OPEN
+    was_previous_character_close_paren = False
+    for each_index in range(scan_start_index, len(command)):
+        current_character = command[each_index]
+        if current_character == OPEN_PAREN_CHARACTER:
+            paren_depth += 1
+            was_previous_character_close_paren = False
+            continue
+        if current_character != CLOSE_PAREN_CHARACTER:
+            was_previous_character_close_paren = False
+            continue
+        paren_depth -= 1
+        if paren_depth == 0:
+            return was_previous_character_close_paren
+        was_previous_character_close_paren = True
+    return False
+
+
+def _has_unsafe_dollar_paren_expansion(command: str) -> bool:
+    """Return True for a `$(` that is not a safe `$((...))` arithmetic pair."""
+    for each_match in DOLLAR_PAREN_PATTERN.finditer(command):
+        is_arithmetic_style_open = (
+            command[each_match.end() : each_match.end() + 1] == OPEN_PAREN_CHARACTER
+        )
+        if not is_arithmetic_style_open:
+            return True
+        if not _closes_as_arithmetic_expansion(command, each_match.end() + 1):
+            return True
+    return False
+
+
 def has_shell_substitution(command: str) -> bool:
     """Return True when a Bash command carries a live shell substitution.
 
@@ -79,18 +155,18 @@ def has_shell_substitution(command: str) -> bool:
         echo $((2 + 2))                ok:   arithmetic expansion
 
     Single-quoted runs are stripped first because bash substitutes nothing
-    inside them. A backtick preceded by an odd number of backslashes is escaped
-    and stays allowed.
+    inside them. A backtick preceded by an odd backslash count is escaped.
+    A `$((` pair is walked to its terminator (module docstring) to tell
+    real arithmetic from a disguised subshell.
 
     Args:
         command: The raw Bash command string from the tool input.
 
     Returns:
-        True when a substitution the allowlist matcher cannot descend into is
-        present outside single quotes.
+        True when a substitution the matcher cannot descend into is present.
     """
     scannable_command = _strip_single_quoted_runs(command)
-    if DOLLAR_PAREN_PATTERN.search(scannable_command):
+    if _has_unsafe_dollar_paren_expansion(scannable_command):
         return True
     if EVEN_BACKSLASH_BACKTICK_PATTERN.search(scannable_command):
         return True

package/hooks/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -261,6 +261,20 @@ def test_emit_decision_re_emits_silent_deny_fields(
     assert emitted_payload["suppressOutput"] is True
 
 
+def test_dispatcher_denies_subshell_disguised_as_arithmetic_expansion() -> None:
+    """The dispatcher denies a `$((cd X) && Y)` subshell, not only the bare hook.
+
+    `echo $((cd /tmp) && pwd)` opens with a `$((` two-character lookahead
+    match, so a function-level test alone does not prove the block reaches
+    the live Bash tool path.
+    """
+    payload_text = _bash_payload("echo $((cd /tmp) && pwd)")
+    decision, _reason = _decision_from_stdout(
+        _run_process(_DISPATCHER_SCRIPT, payload_text).stdout
+    )
+    assert decision == "deny"
+
+
 def test_dispatch_emits_deny_immediately_and_skips_later_hooks(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],

package/hooks/blocking/test_code_rules_enforcer_banned_noun_word.py

@@ -28,7 +28,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_banned_noun_word_boundary = hook_module.check_banned_noun_word_boundary
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 from code_rules_banned_identifiers import (  # noqa: E402
     _find_banned_noun_word,

package/hooks/blocking/test_code_rules_enforcer_class_docstring_methods.py

@@ -31,7 +31,7 @@ def check_class_docstring_names_public_methods(content: str, file_path: str) ->
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/break_reporter.py"

package/hooks/blocking/test_code_rules_enforcer_dispatch_wiring.py

@@ -1,25 +1,49 @@
-"""Meta-test asserting every check_* function is dispatched from validate_content.
+"""Meta-test asserting every check_* function is reachable from the full gate.
 
 The per-check test modules each prove one ``check_*`` function flags the right
 violation, but none proves the enforcer actually calls that function. A refactor
-that drops a dispatch line from ``validate_content`` leaves every per-check test
-green while the check stops firing at Write/Edit time — the precise failure mode
+that drops a dispatch line from ``validate_content_for_full_gate`` or from one
+of its extension-issue helper functions leaves every per-check test green
+while the check stops firing at Write/Edit time — the precise failure mode
 that would let a dead module-level constant (the ``MEDIUM_TEXT`` class) or an
 orphan CSS class slip past the gate again.
 
-This module reads ``validate_content``'s source and asserts every ``check_*``
-attribute on the enforcer module appears in it. A check that is intentionally
-not wired must be listed in ``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this
-docstring. ``check_unanchored_command_dispatch`` is listed there: it guards a
-``hooks/blocking`` command classifier, and the whole ``validate_content`` verdict
-stays off hook-infrastructure files, so the enforcer dispatches it from
+::
+
+    validate_content_for_full_gate -> _python_extension_issues -> _python_magic_value_and_constant_issues
+                                                                        |
+                                                                        v
+                                                            references check_magic_values
+    -> check_magic_values counts as reachable
+
+    check_unanchored_command_dispatch: called only from
+    _hook_infrastructure_blocking_issues, which the full gate's call graph
+    never reaches -> stays in KNOWN_UNDISPATCHED_CHECKS
+
+This module walks the enforcer's real call graph from
+``validate_content_for_full_gate``, following every direct function call into
+the functions the enforcer module defines, and collects every
+``check_*``/``advise_*`` name each reached function body references — a direct
+call or a bare reference passed on as a callback (the
+``_fragment_or_deferred_check(check_magic_values, ...)`` shape). A name that
+surfaces only in an import statement or a docstring is not a reference inside
+a reached function body, so it does not count; this is what keeps the check
+from going vacuous the way a whole-module substring scan would.
+
+A check that is intentionally not wired must be listed in
+``KNOWN_UNDISPATCHED_CHECKS`` with a reason in this docstring.
+``check_unanchored_command_dispatch`` is listed there: it guards a
+``hooks/blocking`` command classifier, and the whole
+``validate_content_for_full_gate`` verdict stays off hook-infrastructure
+files, so the enforcer dispatches it from
 ``_hook_infrastructure_blocking_issues`` instead. The companion
-``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention; this
-module guards the wiring.
+``test_code_rules_enforcer_cap_meta.py`` guards the payload-cap convention;
+this module guards the wiring.
 """
 
 from __future__ import annotations
 
+import ast
 import importlib.util
 import inspect
 import pathlib
@@ -42,6 +66,8 @@ KNOWN_UNDISPATCHED_CHECKS: frozenset[str] = frozenset(
     {"check_unanchored_command_dispatch"}
 )
 
+DISPATCH_ENTRY_POINT_NAME = "validate_content_for_full_gate"
+
 
 def _all_check_function_names() -> list[str]:
     return [
@@ -52,22 +78,91 @@ def _all_check_function_names() -> list[str]:
     ]
 
 
-def _validate_content_source() -> str:
-    return inspect.getsource(_hook_module.validate_content)
+def _module_level_function_defs(module_tree: ast.Module) -> dict[str, ast.FunctionDef]:
+    """Map each module-level function's name to its definition node."""
+    return {
+        each_node.name: each_node
+        for each_node in module_tree.body
+        if isinstance(each_node, ast.FunctionDef)
+    }
 
 
-def test_every_check_function_is_called_in_validate_content() -> None:
-    all_check_names = set(_all_check_function_names())
-    validate_content_source = _validate_content_source()
-    undispatched_check_names = {
-        each_name for each_name in all_check_names if each_name not in validate_content_source
+def _local_call_targets(function_node: ast.FunctionDef) -> set[str]:
+    """Return the plain-name targets one function directly calls."""
+    return {
+        each_call.func.id
+        for each_call in ast.walk(function_node)
+        if isinstance(each_call, ast.Call) and isinstance(each_call.func, ast.Name)
+    }
+
+
+def _unvisited_local_calls(
+    function_name: str,
+    function_defs_by_name: dict[str, ast.FunctionDef],
+    visited: set[str],
+) -> list[str]:
+    """Return *function_name*'s call targets not already visited by the walk."""
+    function_node = function_defs_by_name.get(function_name)
+    if function_node is None:
+        return []
+    return [each for each in _local_call_targets(function_node) if each not in visited]
+
+
+def _reachable_function_names(
+    start_name: str, function_defs_by_name: dict[str, ast.FunctionDef]
+) -> set[str]:
+    """Return every function name the call graph reaches, starting from start_name."""
+    visited: set[str] = set()
+    pending = [start_name]
+    while pending:
+        each_pending_name = pending.pop()
+        if each_pending_name in visited:
+            continue
+        visited.add(each_pending_name)
+        pending.extend(_unvisited_local_calls(each_pending_name, function_defs_by_name, visited))
+    return visited
+
+
+def _referenced_names(function_node: ast.FunctionDef) -> set[str]:
+    """Return every loaded identifier one function body references.
+
+    A callback-style dispatch (``_fragment_or_deferred_check(check_magic_values,
+    ...)``) passes the check function by bare name rather than calling it
+    directly, so this collects every loaded ``Name``, not only call targets.
+    """
+    return {
+        each_name.id
+        for each_name in ast.walk(function_node)
+        if isinstance(each_name, ast.Name) and isinstance(each_name.ctx, ast.Load)
     }
+
+
+def _reachable_referenced_names(
+    start_name: str, function_defs_by_name: dict[str, ast.FunctionDef]
+) -> set[str]:
+    """Return every identifier referenced by a function the call graph reaches."""
+    reachable_function_names = _reachable_function_names(start_name, function_defs_by_name)
+    referenced_names: set[str] = set()
+    for each_function_name in reachable_function_names:
+        function_node = function_defs_by_name.get(each_function_name)
+        if function_node is not None:
+            referenced_names.update(_referenced_names(function_node))
+    return referenced_names
+
+
+def test_every_check_function_is_reachable_from_the_full_gate() -> None:
+    module_tree = ast.parse(inspect.getsource(_hook_module))
+    function_defs_by_name = _module_level_function_defs(module_tree)
+    reachable_names = _reachable_referenced_names(DISPATCH_ENTRY_POINT_NAME, function_defs_by_name)
+    all_check_names = set(_all_check_function_names())
+    undispatched_check_names = all_check_names - reachable_names
     unexpected_undispatched = undispatched_check_names - KNOWN_UNDISPATCHED_CHECKS
     assert unexpected_undispatched == set(), (
-        f"check_* functions are imported but never called in validate_content: "
-        f"{sorted(unexpected_undispatched)}. Wire each into validate_content so the "
-        f"check fires at Write/Edit time, or list it in KNOWN_UNDISPATCHED_CHECKS "
-        f"with a reason in the test header docstring."
+        f"check_* functions are imported but never reachable from "
+        f"validate_content_for_full_gate's call graph: {sorted(unexpected_undispatched)}. "
+        f"Wire each into validate_content_for_phase or one of its extension-issue "
+        f"helpers so the check fires at Write/Edit time, or list it in "
+        f"KNOWN_UNDISPATCHED_CHECKS with a reason in the test header docstring."
     )
 
 

package/hooks/blocking/test_code_rules_enforcer_docstring_args_signature.py

@@ -30,7 +30,7 @@ def check_docstring_args_match_signature(content: str, file_path: str) -> list[s
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/services.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_prose_wall_illustration.py

@@ -39,7 +39,7 @@ def check_docstring_prose_wall_without_illustration(content: str, file_path: str
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/tally.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_runon_sentence.py

@@ -42,7 +42,7 @@ def check_docstring_runon_sentence(content: str, file_path: str) -> list[str]:
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/run_lifecycle.py"

package/hooks/blocking/test_code_rules_enforcer_docstring_unreferenced_param.py

@@ -32,7 +32,7 @@ def check_documents_unreferenced_parameter(content: str, file_path: str) -> list
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 PRODUCTION_FILE_PATH = "/project/src/per_theme_loop.py"

package/hooks/blocking/test_code_rules_enforcer_fstring_scan.py

@@ -17,7 +17,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_fstring_structural_literals = hook_module.check_fstring_structural_literals
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 PRODUCTION_FILE_PATH = "packages/claude-dev-env/example.py"
 TEST_FILE_PATH = "packages/claude-dev-env/test_example.py"

package/hooks/blocking/test_code_rules_enforcer_ignored_must_check_return.py

@@ -25,7 +25,7 @@ from code_rules_boolean_mustcheck import (  # noqa: E402
     check_ignored_must_check_return as _check_ignored_must_check_return,
 )
 from code_rules_enforcer import (  # noqa: E402
-    validate_content as _validate_content,
+    validate_content_for_full_gate as _validate_content,
 )
 
 code_rules_enforcer = SimpleNamespace(

package/hooks/blocking/test_code_rules_enforcer_inline_tuple_string_magic.py

@@ -23,7 +23,7 @@ assert hook_spec.loader is not None
 hook_module = importlib.util.module_from_spec(hook_spec)
 hook_spec.loader.exec_module(hook_module)
 check_inline_tuple_string_magic = hook_module.check_inline_tuple_string_magic
-validate_content = hook_module.validate_content
+validate_content = hook_module.validate_content_for_full_gate
 
 PRODUCTION_FILE_PATH = "packages/app/services/loader.py"
 TEST_FILE_PATH = "packages/app/services/test_loader.py"

package/hooks/blocking/test_code_rules_enforcer_join_separator_magic.py

@@ -77,7 +77,7 @@ def test_should_grandfather_unchanged_join_separator_in_wide_edit() -> None:
         "    # keep the join separator the same\n"
         "    return ', '.join(str(each_path) for each_path in all_paths)\n"
     )
-    issues = code_rules_enforcer.validate_content(
+    issues = code_rules_enforcer.validate_content_for_full_gate(
         proposed_fragment,
         PRODUCTION_FILE_PATH,
         prior_fragment,
@@ -97,7 +97,7 @@ def test_should_block_new_join_separator_in_wide_edit() -> None:
         "def render(all_paths: list) -> str:\n"
         "    return ', '.join(all_paths)\n"
     )
-    issues = code_rules_enforcer.validate_content(
+    issues = code_rules_enforcer.validate_content_for_full_gate(
         proposed_fragment,
         PRODUCTION_FILE_PATH,
         prior_fragment,

package/hooks/blocking/test_code_rules_enforcer_js_returns_object.py

@@ -1,6 +1,6 @@
 """Enforcer-dispatch tests for the JS returns-object schema-less branch check.
 
-These drive ``validate_content`` end-to-end on a ``.mjs`` payload, so they prove
+These drive ``validate_content_for_full_gate`` end-to-end on a ``.mjs`` payload, so they prove
 the check is wired into the JavaScript branch of the enforcer, not just callable
 in isolation. The drift: a ``function`` whose JSDoc ``@returns {Promise<object>}``
 promises a structured object while one branch returns the agent helper with an
@@ -62,11 +62,11 @@ def _has_returns_object_finding(all_issues: list[str]) -> bool:
 
 def test_enforcer_reports_schema_less_branch_under_returns_object() -> None:
     drift_source = _mixed_schema_mjs()
-    all_issues = code_rules_enforcer.validate_content(drift_source, _MJS_PATH, drift_source)
+    all_issues = code_rules_enforcer.validate_content_for_full_gate(drift_source, _MJS_PATH, drift_source)
     assert _has_returns_object_finding(all_issues)
 
 
 def test_enforcer_accepts_every_branch_with_a_schema() -> None:
     clean_source = _all_schema_mjs()
-    all_issues = code_rules_enforcer.validate_content(clean_source, _MJS_PATH, clean_source)
+    all_issues = code_rules_enforcer.validate_content_for_full_gate(clean_source, _MJS_PATH, clean_source)
     assert not _has_returns_object_finding(all_issues)

package/hooks/blocking/test_code_rules_enforcer_module_docstring_roster.py

@@ -31,7 +31,7 @@ def check_module_docstring_names_public_checks(content: str, file_path: str) ->
 
 
 def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
-    return code_rules_enforcer.validate_content(content, file_path, old_content)
+    return code_rules_enforcer.validate_content_for_full_gate(content, file_path, old_content)
 
 
 HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/code_rules_test_assertions.py"

package/hooks/blocking/test_code_rules_enforcer_naming_pattern.py

@@ -18,7 +18,7 @@ assert _hook_spec.loader is not None
 _hook_module = importlib.util.module_from_spec(_hook_spec)
 _hook_spec.loader.exec_module(_hook_module)
 check_boolean_naming = _hook_module.check_boolean_naming
-validate_content = _hook_module.validate_content
+validate_content = _hook_module.validate_content_for_full_gate
 
 
 PRODUCTION_FILE_PATH = "src/app/feature.py"