claude-dev-env 1.92.0 → 1.93.0

package/hooks/blocking/bash_pre_tool_use_dispatcher.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""PreToolUse dispatcher that hosts the Bash and PowerShell blocking hook chains.
+
+Reads the tool payload from stdin once, selects the hosted hooks applicable to
+the payload's tool name, runs each hook in-process via the shared hosted-hook
+runner, aggregates deny/ask/allow decisions with deny>ask>allow precedence, and
+emits one decision (carrying updatedInput when a rewriter allowed a rewrite, and
+systemMessage / additionalContext / suppressOutput when hosted hooks set them).
+
+A deny short-circuits the remaining chain: once any hosted hook denies, the
+dispatcher aggregates what has run so far, emits that deny immediately, and
+returns so a later process timeout cannot drop an already-known denial. Ask and
+allow continue through the full roster because a later hook may still deny.
+
+A single hosted hook crash fails open: it contributes no decision and does not
+stop the remaining hooks, matching a standalone hook whose uncaught exception
+exits nonzero without blocking the tool call.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+    ALL_BASH_HOSTED_HOOK_ENTRIES,
+    ALLOW_DECISION,
+    ASK_DECISION,
+    CONTEXT_JOIN_SEPARATOR,
+    DENY_DECISION,
+    HOOK_EVENT_NAME,
+    REASON_JOIN_SEPARATOR,
+    BashHostedHookEntry,
+)
+from hooks_constants.hosted_hook_runner import HostedHookRun, run_hook_capturing_output
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+_PERMISSION_DECISION_KEY = "permissionDecision"
+_PERMISSION_REASON_KEY = "permissionDecisionReason"
+_HOOK_SPECIFIC_OUTPUT_KEY = "hookSpecificOutput"
+_UPDATED_INPUT_KEY = "updatedInput"
+_SYSTEM_MESSAGE_KEY = "systemMessage"
+_ADDITIONAL_CONTEXT_KEY = "additionalContext"
+_SUPPRESS_OUTPUT_KEY = "suppressOutput"
+
+
+@dataclass
+class BashDispatcherDecision:
+    """Aggregated outcome across the Bash/PowerShell hosted-hook chain.
+
+    Attributes:
+        decision: The winning permission outcome (deny, ask, allow), or empty
+            when no hosted hook emitted an outcome.
+        reasons: Deny or ask reasons collected from deciding hooks, in run order.
+        updated_input: The rewritten tool_input from an allowing rewriter, or
+            None when no allow carried an updatedInput.
+        all_system_messages: Top-level systemMessage texts from hosted hooks.
+        all_additional_context: hookSpecificOutput.additionalContext texts.
+        should_suppress_output: True when any hosted hook set suppressOutput.
+    """
+
+    decision: str
+    reasons: list[str] = field(default_factory=list)
+    updated_input: dict[str, object] | None = None
+    all_system_messages: list[str] = field(default_factory=list)
+    all_additional_context: list[str] = field(default_factory=list)
+    should_suppress_output: bool = False
+
+
+@dataclass
+class _ParsedHookDecision:
+    """Fields parsed from one hosted hook's stdout."""
+
+    decision: str
+    reason: str
+    updated_input: dict[str, object] | None
+    system_message: str
+    additional_context: str
+    should_suppress_output: bool
+
+
+def select_applicable_entries(tool_name: str) -> list[BashHostedHookEntry]:
+    """Return the ordered hosted-hook entries that apply to tool_name."""
+    return [
+        each_entry
+        for each_entry in ALL_BASH_HOSTED_HOOK_ENTRIES
+        if tool_name in each_entry.applicable_tool_names
+    ]
+
+
+def _empty_parsed_hook_decision() -> _ParsedHookDecision:
+    """Return a non-deciding parse result with empty supplementary fields."""
+    return _ParsedHookDecision(
+        decision="",
+        reason="",
+        updated_input=None,
+        system_message="",
+        additional_context="",
+        should_suppress_output=False,
+    )
+
+
+def _parse_hook_stdout(stdout_text: str) -> _ParsedHookDecision:
+    """Parse one hook's stdout into a decision, reason, rewrite, and context."""
+    stripped_text = stdout_text.strip()
+    if not stripped_text:
+        return _empty_parsed_hook_decision()
+    try:
+        parsed_output = json.loads(stripped_text)
+    except json.JSONDecodeError:
+        return _empty_parsed_hook_decision()
+    if not isinstance(parsed_output, dict):
+        return _empty_parsed_hook_decision()
+    hook_specific = parsed_output.get(_HOOK_SPECIFIC_OUTPUT_KEY, {})
+    if not isinstance(hook_specific, dict):
+        return _empty_parsed_hook_decision()
+    raw_decision = hook_specific.get(_PERMISSION_DECISION_KEY, "")
+    decision = raw_decision if isinstance(raw_decision, str) else ""
+    raw_reason = hook_specific.get(_PERMISSION_REASON_KEY, "")
+    reason = raw_reason if isinstance(raw_reason, str) else ""
+    raw_updated_input = hook_specific.get(_UPDATED_INPUT_KEY)
+    updated_input = raw_updated_input if isinstance(raw_updated_input, dict) else None
+    raw_system_message = parsed_output.get(_SYSTEM_MESSAGE_KEY, "")
+    system_message = raw_system_message if isinstance(raw_system_message, str) else ""
+    raw_additional_context = hook_specific.get(_ADDITIONAL_CONTEXT_KEY, "")
+    additional_context = (
+        raw_additional_context if isinstance(raw_additional_context, str) else ""
+    )
+    should_suppress_output = parsed_output.get(_SUPPRESS_OUTPUT_KEY) is True
+    return _ParsedHookDecision(
+        decision=decision,
+        reason=reason,
+        updated_input=updated_input,
+        system_message=system_message,
+        additional_context=additional_context,
+        should_suppress_output=should_suppress_output,
+    )
+
+
+def aggregate_bash_hook_results(
+    all_runs: list[HostedHookRun],
+) -> BashDispatcherDecision:
+    """Aggregate hosted-hook runs into one deny>ask>allow decision.
+
+    Crashed hooks fail open: they contribute no decision. Reasons are collected
+    from deny and ask outputs. When the winning decision is allow, the first
+    non-empty updatedInput among allow results is carried through so rewriters
+    keep their contract. systemMessage, additionalContext, and suppressOutput
+    from every non-crashed hook are preserved so silent deny shapes (for example
+    destructive_command_blocker's gh-redirect deny) match standalone emission.
+    """
+    all_parsed: list[_ParsedHookDecision] = []
+    for each_run in all_runs:
+        if each_run.did_crash:
+            continue
+        all_parsed.append(_parse_hook_stdout(each_run.captured_stdout))
+
+    decision_precedence = (DENY_DECISION, ASK_DECISION, ALLOW_DECISION)
+    winning_decision = ""
+    for each_candidate in decision_precedence:
+        if any(each_parsed.decision == each_candidate for each_parsed in all_parsed):
+            winning_decision = each_candidate
+            break
+
+    if not winning_decision:
+        return BashDispatcherDecision(decision="")
+
+    all_reasons = [
+        each_parsed.reason
+        for each_parsed in all_parsed
+        if each_parsed.decision in (DENY_DECISION, ASK_DECISION) and each_parsed.reason
+    ]
+    updated_input: dict[str, object] | None = None
+    if winning_decision == ALLOW_DECISION:
+        for each_parsed in all_parsed:
+            if each_parsed.decision == ALLOW_DECISION and each_parsed.updated_input is not None:
+                updated_input = each_parsed.updated_input
+                break
+
+    all_system_messages = [
+        each_parsed.system_message for each_parsed in all_parsed if each_parsed.system_message
+    ]
+    all_additional_context = [
+        each_parsed.additional_context
+        for each_parsed in all_parsed
+        if each_parsed.additional_context
+    ]
+    should_suppress_output = any(
+        each_parsed.should_suppress_output for each_parsed in all_parsed
+    )
+
+    return BashDispatcherDecision(
+        decision=winning_decision,
+        reasons=all_reasons,
+        updated_input=updated_input,
+        all_system_messages=all_system_messages,
+        all_additional_context=all_additional_context,
+        should_suppress_output=should_suppress_output,
+    )
+
+
+def _resolve_hook_script_path(relative_path: str) -> str:
+    """Resolve a hooks/-relative path to an absolute script path."""
+    hooks_root = Path(__file__).resolve().parent.parent
+    return str(hooks_root / relative_path)
+
+
+def _emit_decision(decision: BashDispatcherDecision) -> None:
+    """Write one PreToolUse permission payload to stdout when an outcome exists."""
+    if not decision.decision:
+        return
+    hook_specific: dict[str, object] = {
+        "hookEventName": HOOK_EVENT_NAME,
+        _PERMISSION_DECISION_KEY: decision.decision,
+    }
+    if decision.reasons:
+        hook_specific[_PERMISSION_REASON_KEY] = REASON_JOIN_SEPARATOR.join(decision.reasons)
+    if decision.decision == ALLOW_DECISION and decision.updated_input is not None:
+        hook_specific[_UPDATED_INPUT_KEY] = decision.updated_input
+    if decision.all_additional_context:
+        hook_specific[_ADDITIONAL_CONTEXT_KEY] = CONTEXT_JOIN_SEPARATOR.join(
+            decision.all_additional_context
+        )
+    payload: dict[str, object] = {_HOOK_SPECIFIC_OUTPUT_KEY: hook_specific}
+    if decision.all_system_messages:
+        payload[_SYSTEM_MESSAGE_KEY] = CONTEXT_JOIN_SEPARATOR.join(decision.all_system_messages)
+    if decision.should_suppress_output:
+        payload[_SUPPRESS_OUTPUT_KEY] = True
+    sys.stdout.write(json.dumps(payload) + "\n")
+    sys.stdout.flush()
+
+
+def _run_is_deny(hook_run: HostedHookRun) -> bool:
+    """Return True when a non-crashed run carries a deny decision."""
+    if hook_run.did_crash:
+        return False
+    parsed_decision = _parse_hook_stdout(hook_run.captured_stdout)
+    return parsed_decision.decision == DENY_DECISION
+
+
+def dispatch(payload_text: str, tool_name: str) -> None:
+    """Run applicable hosted hooks and emit the aggregated decision.
+
+    Emits and returns as soon as any hosted hook denies so a process timeout
+    later in the chain cannot fail-open past an already-known denial.
+    """
+    applicable_entries = select_applicable_entries(tool_name)
+    all_runs: list[HostedHookRun] = []
+    for each_entry in applicable_entries:
+        script_path = _resolve_hook_script_path(each_entry.script_relative_path)
+        hook_run = run_hook_capturing_output(script_path, payload_text)
+        all_runs.append(hook_run)
+        if _run_is_deny(hook_run):
+            aggregated_decision = aggregate_bash_hook_results(all_runs)
+            _emit_decision(aggregated_decision)
+            return
+    aggregated_decision = aggregate_bash_hook_results(all_runs)
+    _emit_decision(aggregated_decision)
+
+
+def main() -> None:
+    """Read stdin once and dispatch the Bash/PowerShell hosted-hook chain."""
+    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)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/code_rules_dead_module_constant.py

@@ -33,12 +33,20 @@ The scan is deliberately conservative to keep false positives near zero:
   ``from <module> import`` whose final dotted segment equals the written
   module's filename stem, so a genuine cross-tree consumer of this constants
   module keeps the constant live while a same-named constant exported by an
-  unrelated module never masks a dead one. A module outside any repository is
+  unrelated module never masks a dead one. The widened pass reads a repository
+  file only to test whether its text names the written module's filename stem;
+  a file that never mentions the stem cannot carry such an import, so it is
+  skipped without spending scan-cap budget, keeping the widened pass bounded to
+  the handful of candidate importer files even in a large repository. A module
+  outside any repository is
   judged on the package-tree scan alone, and the widened pass skips the package
   subtree the first pass already covered, so no file is read twice.
-- The combined file count of the package-tree and widened passes is bounded by a
-  cap, so a write under an unexpectedly large tree cannot stall the hook; a write
-  whose scan hits the cap is treated as "cannot prove dead" and flags nothing.
+- Two caps bound the widened pass: a read-attempt cap bounds how many files
+  the pass opens and reads at all while testing for the stem, and a separate
+  parse cap bounds how many of those files (the ones that do name the stem)
+  get parsed and have their names collected. Either cap bounds the pass even
+  under an unexpectedly large tree; a write whose scan hits either cap is
+  treated as "cannot prove dead" and flags nothing.
 - Test modules under the scanned tree still count as references, so a constant
   used only by a test stays live.
 """
@@ -71,6 +79,7 @@ from hooks_constants.dead_module_constant_constants import (  # noqa: E402
     GIT_DIRECTORY_NAME,
     MAX_DEAD_MODULE_CONSTANT_ISSUES,
     MAX_SCAN_ROOT_FILE_COUNT,
+    MAX_SCAN_ROOT_READ_COUNT,
     MINIMUM_UPPER_SNAKE_LENGTH,
     PYTHON_SOURCE_SUFFIX,
 )
@@ -328,6 +337,42 @@ def _is_under_directory(candidate_path: Path, ancestor_directory: Path) -> bool:
     return True
 
 
+def _read_candidate_source(file_path: Path, required_substring: str | None) -> str | None:
+    """Return a module's text, or None when it is not a reference-scan candidate.
+
+    ::
+
+        required_substring = None                 -> read and keep every file
+        required_substring = the module stem      -> keep only files naming it
+            from pkg.foo_constants import BAR  ->  names the stem  ->  candidate
+            def unrelated() -> int: ...        ->  no stem mention ->  skipped
+
+    The widened repository pass looks only for a ``from <module> import`` whose
+    final dotted segment equals the constants module's filename stem, and such an
+    import always spells that stem in the file's text. A file whose text never
+    mentions the stem cannot carry the import, so returning None for it lets the
+    caller skip the file without spending scan-cap budget, which keeps the widened
+    pass bounded to the candidate importer files even under a large repository.
+
+    Args:
+        file_path: The ``.py`` module to read.
+        required_substring: A stem every candidate file's text must contain, or
+            None to keep every readable file (the package-tree pass keeps all).
+
+    Returns:
+        The file's text when it is readable and, when ``required_substring`` is
+        set, contains that stem; None when the file cannot be read or does not
+        name the stem.
+    """
+    try:
+        source_text = file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    if required_substring is not None and required_substring not in source_text:
+        return None
+    return source_text
+
+
 def _collect_names_under_root(
     scan_root: Path,
     written_path: Path,
@@ -335,17 +380,33 @@ def _collect_names_under_root(
     extract_names: Callable[[str], set[str]],
     already_scanned_count: int = 0,
     excluded_subtree: Path | None = None,
+    required_substring: str | None = None,
 ) -> tuple[set[str], int, bool]:
     """Collect referenced names under the scan root via a per-module extractor.
 
     Walks every ``.py`` module under ``scan_root`` (excluding the written module
     itself, and any module under ``excluded_subtree``), applies ``extract_names``
-    to each module's text, and unions the result onto ``all_seed_names``. Reading
-    stops once the running file count exceeds the configured cap so a write under
-    an unexpectedly large tree cannot stall the hook; the boolean signals the
-    caller to treat that case as "cannot prove dead". The ``excluded_subtree``
-    skip keeps the widened repository scan from re-reading a file the
-    package-tree scan already covered.
+    to each module's text, and unions the result onto ``all_seed_names``. Two
+    caps bound the walk so a write under an unexpectedly large tree cannot
+    stall the hook:
+
+    ::
+
+        read_attempt_count  -> every file this call opens and reads,
+                                whether or not it turns out to be a
+                                candidate -> capped by MAX_SCAN_ROOT_READ_COUNT
+        scanned_file_count  -> only the files that pass the candidate
+                                filter and get parsed for names       -> capped
+                                by MAX_SCAN_ROOT_FILE_COUNT
+
+    Either cap tripping returns ``cap_was_hit=True``, which signals the caller
+    to treat the write as "cannot prove dead". The ``excluded_subtree`` skip
+    keeps the widened repository scan from re-reading a file the package-tree
+    scan already covered. When ``required_substring`` is set, a module whose
+    text never contains that stem is skipped after being read but before it is
+    counted toward ``scanned_file_count`` or parsed, so the parse-and-collect
+    work stays bounded to the candidate importer files even though the read
+    cap still bounds the raw disk reads across the whole tree.
 
     Args:
         scan_root: The directory tree to scan.
@@ -357,10 +418,17 @@ def _collect_names_under_root(
         extract_names: Maps one module's source text to the set of names it
             contributes — the generous reference collector for the package-tree
             pass, the stem-bound import collector for the widened pass.
-        already_scanned_count: The file count accumulated by a prior pass, so the
-            cap bounds the combined work of the package-tree and widened passes.
+        already_scanned_count: The parsed-file count accumulated by a prior
+            pass, so the parse cap bounds the combined work of the
+            package-tree and widened passes.
         excluded_subtree: A resolved directory whose ``.py`` modules are skipped,
             or None to scan every file under the root.
+        required_substring: A stem a file's text must contain to count as a
+            scan candidate, or None to scan every file. The widened pass passes
+            the written module's filename stem so a file that never names the
+            module is skipped before it is counted or parsed, spending parse
+            budget only on the candidate importer files, while the read cap
+            still bounds how many files get read looking for that stem.
 
     Returns:
         A (collected_names, running_count, cap_was_hit) triple. collected_names
@@ -372,6 +440,7 @@ def _collect_names_under_root(
     collected_names = set(all_seed_names)
     written_path_key = os.path.normcase(str(written_path))
     scanned_file_count = already_scanned_count
+    read_attempt_count = 0
     for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
         if not each_path.is_file():
             continue
@@ -380,13 +449,15 @@ def _collect_names_under_root(
             continue
         if excluded_subtree is not None and _is_under_directory(resolved_path, excluded_subtree):
             continue
+        read_attempt_count += 1
+        if read_attempt_count > MAX_SCAN_ROOT_READ_COUNT:
+            return collected_names, scanned_file_count, True
+        sibling_source = _read_candidate_source(each_path, required_substring)
+        if sibling_source is None:
+            continue
         scanned_file_count += 1
         if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
             return collected_names, scanned_file_count, True
-        try:
-            sibling_source = each_path.read_text(encoding="utf-8")
-        except (OSError, UnicodeDecodeError):
-            continue
         collected_names |= extract_names(sibling_source)
     return collected_names, scanned_file_count, False
 
@@ -550,6 +621,7 @@ def check_dead_module_constants(
                 collect_qualified_imports,
                 already_scanned_count=scanned_file_count,
                 excluded_subtree=scan_root,
+                required_substring=written_path.stem,
             )
             if widened_cap_was_hit:
                 return []

package/hooks/blocking/code_rules_enforcer.py

@@ -181,6 +181,10 @@ from code_rules_test_branching_except import (  # noqa: E402
 from code_rules_test_isolation import (  # noqa: E402
     check_tests_use_isolated_filesystem_paths,
 )
+from code_rules_test_layout import (  # noqa: E402
+    check_dead_test_module_constant,
+    check_unused_test_helper_parameter,
+)
 from code_rules_type_escape import (  # noqa: E402
     check_boundary_types,
     check_type_escape_hatches,
@@ -324,6 +328,8 @@ def validate_content(
         all_issues.extend(check_stub_implementations(effective_content, file_path))
         all_issues.extend(check_typed_dict_encode_decode(effective_content, file_path))
         all_issues.extend(check_test_branching_in_production(effective_content, file_path))
+        all_issues.extend(check_dead_test_module_constant(effective_content, file_path))
+        all_issues.extend(check_unused_test_helper_parameter(effective_content, file_path))
         all_issues.extend(check_bare_except(effective_content, file_path))
         all_issues.extend(check_thin_wrapper_files(effective_content, file_path))
         all_issues.extend(check_zero_payload_function_alias(effective_content, file_path))

package/hooks/blocking/code_rules_imports_logging.py

@@ -115,7 +115,16 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
 
 
 def check_imports_at_top(content: str) -> list[str]:
-    """Check for imports inside functions (Python only).
+    """Check for imports below the top import block (Python only).
+
+    Two placements are flagged. First, an import inside a function body. Second,
+    a module-scope import (indent zero) that sits below the first top-level
+    ``def`` or ``class`` definition — the "imports mid-file after functions"
+    drift, where the imports never enter a function body yet still break the
+    imports-at-top rule. An indented import inside a guarded block below a
+    definition (an ``if __name__ == "__main__":`` guard, a ``try`` fallback) is
+    left alone because only indent-zero module-scope imports are checked for the
+    below-definition case.
 
     An import lexically inside an ``if TYPE_CHECKING:`` block is exempt.
     An import inside a function body is flagged even if the file uses TYPE_CHECKING
@@ -146,7 +155,9 @@ def check_imports_at_top(content: str) -> list[str]:
     issues: list[str] = []
     lines = content.split("\n")
     is_inside_function = False
+    has_seen_top_level_definition = False
     function_indent = 0
+    module_scope_indent = 0
     type_checking_block_indent = NOT_INSIDE_TYPE_CHECKING_BLOCK
     active_triple_quote_delimiter: str | None = None
 
@@ -180,6 +191,16 @@ def check_imports_at_top(content: str) -> list[str]:
         if function_match:
             is_inside_function = True
             function_indent = len(function_match.group(1)) if function_match.group(1) else 0
+            if function_indent == module_scope_indent:
+                has_seen_top_level_definition = True
+            active_triple_quote_delimiter = _update_triple_quote_state_for_line(
+                each_line, active_triple_quote_delimiter
+            )
+            continue
+
+        class_match = re.match(r"^(\s*)class\s+\w+", each_line)
+        if class_match and len(class_match.group(1)) == module_scope_indent:
+            has_seen_top_level_definition = True
             active_triple_quote_delimiter = _update_triple_quote_state_for_line(
                 each_line, active_triple_quote_delimiter
             )
@@ -194,6 +215,18 @@ def check_imports_at_top(content: str) -> list[str]:
             if stripped.startswith(ALL_IMPORT_STATEMENT_PREFIXES):
                 issues.append(f"Line {each_line_number}: Import inside function - move to top of file")
 
+        is_module_scope_import = (
+            current_indent == module_scope_indent
+            and not is_inside_function
+            and not is_inside_type_checking_block
+            and stripped.startswith(ALL_IMPORT_STATEMENT_PREFIXES)
+        )
+        if is_module_scope_import and has_seen_top_level_definition:
+            issues.append(
+                f"Line {each_line_number}: Import after top-level definition - "
+                "move imports to top of file"
+            )
+
         active_triple_quote_delimiter = _update_triple_quote_state_for_line(
             each_line, active_triple_quote_delimiter
         )

package/hooks/blocking/code_rules_paths_syspath.py

@@ -40,7 +40,7 @@ from hooks_constants.sys_path_insert_constants import (  # noqa: E402
 def check_hardcoded_user_paths(content: str, file_path: str) -> list[str]:
     """Flag string literals naming a specific user's home directory.
 
-    Catches non-portable paths like `C:/Users/jon/...`, `/Users/alice/...`,
+    Catches non-portable paths like `C:/Users/example/...`, `/Users/alice/...`,
     and `/home/bob/...` that surface in production code.
     Test files, config/ files, workflow registry files, migration files,
     and hook infrastructure files are exempt. Hook infrastructure exemption