claude-dev-env 8.105.2 → 8.106.1

package/hooks/blocking/transcript_root_powershell_starts.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+"""PowerShell cmdlet search starts for the transcript root search gate.
+
+Reads the paths and recursion of a ``Get-ChildItem`` or ``Select-String``
+call. ``-Path`` and ``-LiteralPath`` values and positional tokens are paths,
+split on commas. An option off the switch list takes the next token as its
+value unless the next token is an option, so ``-ErrorAction 0`` never reads
+as a path and ``-Verbose -Recurse`` still recurses. An abbreviation that names
+one option, such as ``-Pa`` or ``-Dep``, reads as its full name. ``-Depth`` decides
+recursion when given, ``0`` meaning one level; otherwise ``-Recurse`` does.
+"""
+
+from __future__ import annotations
+
+import collections
+import sys
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_root_directory not in sys.path:
+        sys.path.insert(0, _hooks_root_directory)
+    from blocking.transcript_root_search_starts import (
+        OptionValue,
+        SearchStart,
+        is_option,
+        next_value,
+        starts_or_current_directory,
+    )
+    from hooks_constants import transcript_root_search_gate_constants as search_rules
+    from hooks_constants import unscoped_search_blocker_constants as walk_flags
+    from hooks_constants.pytest_invocation import unquoted_token
+except ImportError as import_error:
+    raise ImportError(
+        "The transcript_root_powershell_starts module cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _split_path_list(path_text: str) -> list[str]:
+    return [
+        each_part
+        for each_part in unquoted_token(path_text).split(
+            search_rules.POWERSHELL_PATH_LIST_SEPARATOR
+        )
+        if each_part
+    ]
+
+
+def _canonical_option_name(option_name: str) -> str:
+    """Return the option a unique abbreviation such as ``-pa`` or ``-dep`` names, else the name."""
+    is_too_short = len(option_name) < search_rules.POWERSHELL_MINIMUM_ABBREVIATION_LENGTH
+    if is_too_short or option_name in search_rules.ALL_POWERSHELL_ABBREVIABLE_OPTIONS:
+        return option_name
+    all_matching_options = [
+        each_option
+        for each_option in search_rules.ALL_POWERSHELL_ABBREVIABLE_OPTIONS
+        if each_option.startswith(option_name)
+    ]
+    return all_matching_options[0] if len(all_matching_options) == 1 else option_name
+
+
+def _powershell_arguments(all_arguments: list[str]) -> tuple[list[str], list[OptionValue]]:
+    """Return a cmdlet call's paths and options; an option off the switch list takes a value."""
+    all_paths: list[str] = []
+    all_options: list[OptionValue] = []
+    all_remaining = collections.deque(all_arguments)
+    while all_remaining:
+        bare_token = unquoted_token(all_remaining.popleft())
+        if not is_option(bare_token):
+            all_paths.extend(_split_path_list(bare_token))
+            continue
+        option_name, glued_separator, glued_value = bare_token.partition(
+            search_rules.POWERSHELL_GLUED_VALUE_SEPARATOR
+        )
+        option_name = _canonical_option_name(option_name.lower())
+        takes_spaced_value = (
+            not glued_separator
+            and option_name not in search_rules.ALL_POWERSHELL_SWITCH_OPTIONS
+            and bool(all_remaining)
+            and not is_option(all_remaining[0])
+        )
+        option_value = next_value(all_remaining) if takes_spaced_value else glued_value
+        all_options.append((option_name, unquoted_token(option_value)))
+        if option_name in walk_flags.ALL_POWERSHELL_PATH_FLAGS:
+            all_paths.extend(_split_path_list(option_value))
+    return all_paths, all_options
+
+
+def _powershell_listing_is_recursive(all_options: list[OptionValue]) -> bool:
+    all_depth_values = [
+        each_value
+        for each_name, each_value in all_options
+        if each_name == search_rules.POWERSHELL_DEPTH_OPTION
+    ]
+    if all_depth_values:
+        return all_depth_values[-1] != search_rules.POWERSHELL_NON_RECURSIVE_DEPTH
+    return any(
+        each_name in walk_flags.ALL_POWERSHELL_RECURSE_FLAGS
+        and (not each_value or each_value.lower() in walk_flags.ALL_TRUTHY_RECURSE_COLON_VALUES)
+        for each_name, each_value in all_options
+    )
+
+
+def powershell_listing_search_starts(all_arguments: list[str]) -> list[SearchStart]:
+    """Return the starts of a ``Get-ChildItem`` call, or of ``ls`` under PowerShell."""
+    all_paths, all_options = _powershell_arguments(all_arguments)
+    return starts_or_current_directory(all_paths, _powershell_listing_is_recursive(all_options))
+
+
+def select_string_search_starts(all_arguments: list[str]) -> list[SearchStart]:
+    """Return the starts of a ``Select-String`` call, which reads only the paths it names."""
+    all_paths, _all_options = _powershell_arguments(all_arguments)
+    return [SearchStart(each_path, False) for each_path in all_paths]

package/hooks/blocking/transcript_root_search_gate.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: deny a recursive walk or content search over a Claude transcript root.
+
+A transcript root is a ``projects`` folder directly under ``.claude``, under
+``.claude-<name>``, or under ``.claude-profiles/<profile>``. It holds one
+folder per project and thousands of JSONL session transcripts, so a walk that
+starts there reads every transcript and runs for minutes. The gate denies a
+search start that names a transcript root with no project folder after it,
+when the search recurses, and a start whose first segment after the root is
+a bare wildcard such as ``*`` or ``**`` that descends into every project
+folder. A name-filtered listing of the root, such as ``Get-ChildItem <root>
+-Directory -Filter "*id*"`` or ``Glob(pattern="*id*", path=<root>)``, passes,
+and so does any walk inside one project folder.
+
+::
+
+    Get-ChildItem $p -Recurse -Filter *.jsonl      flag  ($p bound to a root earlier in the command)
+    Get-ChildItem $p -Directory -Filter "*01WU*"   ok    (one-level name listing)
+    grep needle ~/.claude/projects/*/*.jsonl       flag  (bare wildcard over every folder)
+    Grep(path="~/.claude/projects")                flag  (Grep always recurses)
+
+Shell variables assigned in the same command, such as ``$p="..."`` or
+``p=...``, are expanded before the path is read. The Bash and PowerShell
+tools reach the gate through ``blocking/bash_pre_tool_use_dispatcher.py``;
+``hooks.json`` registers it directly for the Grep and Glob tools.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_root_directory not in sys.path:
+        sys.path.insert(0, _hooks_root_directory)
+    from hooks_constants import transcript_root_search_gate_constants as search_rules
+    from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        DENY_DECISION,
+        HOOK_EVENT_NAME,
+    )
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.pre_tool_use_stdin import print_decision_from_stdin
+    from blocking.transcript_root_search_starts import (
+        SearchStart,
+        file_search_tool_start,
+        walked_transcript_root,
+    )
+    from blocking.transcript_root_shell_starts import shell_command_search_starts
+except ImportError as import_error:
+    raise ImportError(
+        "The transcript root search gate cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _call_search_starts(
+    tool_name: str, all_tool_input: dict[str, object], cwd: str
+) -> list[SearchStart]:
+    if tool_name in ALL_BASH_AND_POWERSHELL_TOOL_NAMES:
+        command = all_tool_input.get(search_rules.TOOL_INPUT_COMMAND_KEY)
+        if not isinstance(command, str):
+            return []
+        return shell_command_search_starts(
+            command, cwd, tool_name == search_rules.POWERSHELL_TOOL_NAME
+        )
+    if tool_name in search_rules.ALL_FILE_SEARCH_TOOL_NAMES:
+        return [file_search_tool_start(tool_name, all_tool_input, cwd)]
+    return []
+
+
+def transcript_root_decision(all_hook_payload: dict[str, object]) -> dict[str, object] | None:
+    """Return the deny decision for a search that walks a transcript root, else None.
+
+    Args:
+        all_hook_payload: The PreToolUse payload the hook read from stdin.
+    """
+    tool_name = all_hook_payload.get(search_rules.PAYLOAD_TOOL_NAME_KEY)
+    all_tool_input = all_hook_payload.get(search_rules.PAYLOAD_TOOL_INPUT_KEY)
+    raw_cwd = all_hook_payload.get(search_rules.PAYLOAD_CWD_KEY)
+    if not isinstance(tool_name, str) or not isinstance(all_tool_input, dict):
+        return None
+    cwd = raw_cwd if isinstance(raw_cwd, str) else ""
+    all_walked_roots = (
+        walked_transcript_root(each_start)
+        for each_start in _call_search_starts(tool_name, all_tool_input, cwd)
+    )
+    transcript_root = next((each_root for each_root in all_walked_roots if each_root), None)
+    if transcript_root is None:
+        return None
+    deny_reason = search_rules.TRANSCRIPT_ROOT_DENY_REASON_TEMPLATE.format(root=transcript_root)
+    log_hook_block(
+        search_rules.GATE_HOOK_NAME,
+        HOOK_EVENT_NAME,
+        deny_reason,
+        tool_name,
+        json.dumps(all_tool_input),
+    )
+    return _deny_decision(deny_reason)
+
+
+def _deny_decision(deny_reason: str) -> dict[str, object]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": DENY_DECISION,
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+
+
+def main() -> None:
+    """Deny a search that walks a Claude transcript root, or stay quiet."""
+    print_decision_from_stdin(transcript_root_decision)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/transcript_root_search_starts.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Search starts for the transcript root search gate.
+
+A search start is the path a search begins at and whether the search recurses
+from it. This module decides whether a start walks every project folder under
+a Claude transcript root, reads the start of a Grep or Glob tool call, and
+holds the option helpers the shell readers share.
+``blocking/transcript_root_shell_starts.py`` and
+``blocking/transcript_root_powershell_starts.py`` read the starts of a shell
+command, and ``blocking/transcript_root_search_gate.py`` denies the call when
+one walks a root.
+"""
+
+from __future__ import annotations
+
+import collections
+import posixpath
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+try:
+    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+    if _hooks_root_directory not in sys.path:
+        sys.path.insert(0, _hooks_root_directory)
+    from hooks_constants import transcript_root_search_gate_constants as search_rules
+    from hooks_constants.pytest_invocation import unquoted_token
+except ImportError as import_error:
+    raise ImportError(
+        "The transcript root gate helpers cannot import their dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+OptionValue = tuple[str, str]
+
+
+@dataclass(frozen=True)
+class SearchStart:
+    """One place a search begins.
+
+    Attributes:
+        path_text: The path or glob the search starts from, as the call names it.
+        is_recursive: True when the search descends below the path on its own.
+    """
+
+    path_text: str
+    is_recursive: bool
+
+
+def normalized_path(path_text: str) -> str:
+    """Return the path with quotes removed, forward slashes, and ``.`` and ``..`` folded.
+
+    ::
+
+        '"C:\\\\h\\\\.claude\\\\projects\\\\"'   -> "C:/h/.claude/projects"
+        "~/.claude/projects/C--x/../"          -> "~/.claude/projects"
+
+    Args:
+        path_text: A path token, possibly quoted or with backslashes.
+    """
+    forward_slash_path = unquoted_token(path_text.strip()).replace(
+        search_rules.WINDOWS_PATH_SEPARATOR, search_rules.PATH_SEPARATOR
+    )
+    if not forward_slash_path:
+        return forward_slash_path
+    return posixpath.normpath(forward_slash_path)
+
+
+def joined_path(base_directory: str, path_text: str) -> str:
+    """Return the path read from the base directory, or the path itself when it is absolute.
+
+    Args:
+        base_directory: The directory a relative path resolves from, or empty when unknown.
+        path_text: The path a command or tool call names.
+    """
+    bare_path = unquoted_token(path_text.strip())
+    if not base_directory or search_rules.ABSOLUTE_PATH_PATTERN.match(bare_path):
+        return bare_path
+    return normalized_path(base_directory) + search_rules.PATH_SEPARATOR + bare_path
+
+
+def is_option(token: str) -> bool:
+    """Return True for a token that starts with ``-`` and holds more than the dash."""
+    bare_token = unquoted_token(token)
+    return len(bare_token) > 1 and bare_token.startswith(search_rules.OPTION_PREFIX)
+
+
+def next_value(all_remaining: collections.deque[str]) -> str:
+    """Take the next token off the queue, unquoted, or empty when none is left."""
+    return unquoted_token(all_remaining.popleft()) if all_remaining else ""
+
+
+def is_recursive_unless_shallow(all_depth_values: list[str], is_recursive_otherwise: bool) -> bool:
+    """Return whether a search recurses; the last depth value decides when one is given."""
+    if all_depth_values:
+        return all_depth_values[-1] not in search_rules.ALL_SHALLOW_DEPTH_VALUES
+    return is_recursive_otherwise
+
+
+def starts_or_current_directory(all_paths: list[str], is_recursive: bool) -> list[SearchStart]:
+    """Return one start per path, or one at the current directory when no path is given."""
+    return [
+        SearchStart(each_path, is_recursive)
+        for each_path in all_paths or [search_rules.CURRENT_DIRECTORY]
+    ]
+
+
+def _walks_every_project_folder(all_segments_below_root: list[str], is_recursive: bool) -> bool:
+    if not all_segments_below_root:
+        return is_recursive
+    first_segment, *all_deeper_segments = all_segments_below_root
+    if search_rules.WILDCARD_ONLY_SEGMENT_PATTERN.fullmatch(first_segment) is None:
+        return False
+    return is_recursive or bool(all_deeper_segments)
+
+
+def walked_transcript_root(search_start: SearchStart) -> str | None:
+    """Return the transcript root a search start walks, or None when it stays scoped.
+
+    ::
+
+        SearchStart("~/.claude/projects", True)              -> "~/.claude/projects"
+        SearchStart("~/.claude/projects", False)             -> None
+        SearchStart("~/.claude/projects/*/*.jsonl", False)   -> "~/.claude/projects"
+        SearchStart("~/.claude/projects/*01WU*", False)      -> None
+        SearchStart("~/.claude/projects/C--repo", True)      -> None
+
+    Args:
+        search_start: The path the search starts from and whether it recurses.
+    """
+    start_path = normalized_path(search_start.path_text)
+    root_match = search_rules.TRANSCRIPT_ROOT_PATTERN.search(start_path)
+    if root_match is None:
+        return None
+    all_segments_below_root = [
+        each_segment
+        for each_segment in start_path[root_match.end() :].split(search_rules.PATH_SEPARATOR)
+        if each_segment
+    ]
+    if not _walks_every_project_folder(all_segments_below_root, search_start.is_recursive):
+        return None
+    return start_path[: root_match.end()]
+
+
+def file_search_tool_start(
+    tool_name: str, all_tool_input: dict[str, object], cwd: str
+) -> SearchStart:
+    """Return where a Grep or Glob tool call starts its search.
+
+    Grep always recurses from its path. Glob reads its pattern below its path,
+    or alone when the pattern is absolute, and recurses when the pattern holds
+    ``**``. A relative path resolves from the session working directory.
+
+    Args:
+        tool_name: ``Grep`` or ``Glob``.
+        all_tool_input: The tool call's input.
+        cwd: The session working directory, used when the call names no path.
+    """
+    raw_path = all_tool_input.get(search_rules.TOOL_INPUT_PATH_KEY)
+    base_path = joined_path(cwd, raw_path) if isinstance(raw_path, str) and raw_path else cwd
+    if tool_name != search_rules.GLOB_TOOL_NAME:
+        return SearchStart(base_path, True)
+    raw_pattern = all_tool_input.get(search_rules.TOOL_INPUT_PATTERN_KEY)
+    pattern = raw_pattern if isinstance(raw_pattern, str) else ""
+    return SearchStart(
+        joined_path(base_path, pattern), search_rules.RECURSIVE_GLOB_SEGMENT in pattern
+    )