claude-dev-env 8.105.1 → 8.106.0

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
+    )

package/hooks/blocking/transcript_root_shell_starts.py

@@ -0,0 +1,368 @@
+#!/usr/bin/env python3
+"""Shell command search starts for the transcript root search gate.
+
+Reads where each program in a Bash or PowerShell command starts reading and
+whether it recurses. ``find``, ``grep``, ``rg``, ``ag``, ``ack``, ``fd``,
+``ls``, ``tree``, ``Get-ChildItem`` and ``Select-String`` follow their own
+option grammar; any other program reads its plain arguments without
+recursion, so ``cat <root>/*/*.jsonl`` still counts as a walk.
+
+Each tokenization of the command runs in order with its own state: variables
+expand from the assignments before them, PowerShell names without regard to
+case, and a relative path resolves from the session directory or the last
+``cd`` or ``Set-Location`` before it, and ``popd`` or ``Pop-Location``
+returns to the folder before the matching ``pushd`` or ``Push-Location``. A
+search with no path starts there.
+"""
+
+from __future__ import annotations
+
+import collections
+import re
+import sys
+from collections.abc import Callable
+from functools import partial
+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_powershell_starts import (
+        powershell_listing_search_starts,
+        select_string_search_starts,
+    )
+    from blocking.transcript_root_search_starts import (
+        OptionValue,
+        SearchStart,
+        is_option,
+        is_recursive_unless_shallow,
+        joined_path,
+        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.destructive_command_segment_constants import FIND_PROGRAM_NAME
+    from hooks_constants.pytest_invocation import unquoted_token
+    from hooks_constants.shell_command_pipeline import (
+        all_operator_aware_tokenizations,
+        join_line_continuations,
+        scannable_command_lines,
+        segments_with_following_operator,
+    )
+    from hooks_constants.shell_command_wrappers import (
+        all_wrapped_command_texts,
+        segment_program_and_arguments,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "The transcript_root_shell_starts module cannot import its dependencies; "
+        "ensure the hooks directory is importable."
+    ) from import_error
+
+
+def _assignment_from_segment(all_segment_tokens: list[str]) -> tuple[str, str] | None:
+    """Return the name and value a segment assigns, such as ``p=x`` or ``$p = "x"``, else None."""
+    prefix_word_count = 0
+    while (
+        prefix_word_count < len(all_segment_tokens)
+        and all_segment_tokens[prefix_word_count].lower()
+        in search_rules.ALL_ASSIGNMENT_PREFIX_WORDS
+    ):
+        prefix_word_count += 1
+    all_tokens = all_segment_tokens[prefix_word_count:]
+    if len(all_tokens) == 1:
+        assignment_match = search_rules.SHELL_ASSIGNMENT_PATTERN.match(all_tokens[0])
+        if assignment_match is not None:
+            return assignment_match["name"], unquoted_token(assignment_match["value"])
+    if (
+        len(all_tokens) == search_rules.SPACED_ASSIGNMENT_TOKEN_COUNT
+        and all_tokens[1] == search_rules.SPACED_ASSIGNMENT_OPERATOR
+    ):
+        name_match = search_rules.SPACED_ASSIGNMENT_NAME_PATTERN.match(all_tokens[0])
+        if name_match is not None:
+            return name_match["name"], unquoted_token(all_tokens[2])
+    return None
+
+
+def _expanded_token(token: str, all_bindings: dict[str, str]) -> str:
+    if search_rules.SHELL_VARIABLE_SIGIL not in token:
+        return token
+    expanded_token = token
+    for each_name, each_value in all_bindings.items():
+        reference_pattern = search_rules.SHELL_VARIABLE_REFERENCE_TEMPLATE.format(
+            name=re.escape(each_name)
+        )
+        expanded_token = re.sub(
+            reference_pattern,
+            each_value.replace("\\", "\\\\"),
+            expanded_token,
+            flags=re.IGNORECASE,
+        )
+    return expanded_token
+
+
+def _long_option(
+    grammar: search_rules.PosixSearchGrammar,
+    bare_token: str,
+    all_remaining: collections.deque[str],
+) -> OptionValue:
+    option_name, glued_separator, glued_value = bare_token.partition(
+        search_rules.GLUED_OPTION_VALUE_SEPARATOR
+    )
+    if glued_separator:
+        return option_name, unquoted_token(glued_value)
+    if option_name in grammar.all_value_options:
+        return option_name, next_value(all_remaining)
+    return option_name, ""
+
+
+def _short_option_cluster(
+    grammar: search_rules.PosixSearchGrammar,
+    bare_token: str,
+    all_remaining: collections.deque[str],
+) -> list[OptionValue]:
+    """Return each option in a cluster such as ``-rC2``; a value letter takes the rest or the next token."""
+    all_options: list[OptionValue] = []
+    for each_index, each_letter in enumerate(bare_token[1:], start=1):
+        option_name = search_rules.OPTION_PREFIX + each_letter
+        if each_letter in grammar.all_value_letters:
+            glued_value = bare_token[each_index + 1 :].removeprefix(
+                search_rules.GLUED_OPTION_VALUE_SEPARATOR
+            )
+            all_options.append((option_name, glued_value or next_value(all_remaining)))
+            return all_options
+        all_options.append((option_name, ""))
+    return all_options
+
+
+def _options_in_token(
+    grammar: search_rules.PosixSearchGrammar,
+    bare_token: str,
+    all_remaining: collections.deque[str],
+) -> list[OptionValue]:
+    if bare_token.startswith(search_rules.LONG_OPTION_PREFIX):
+        return [_long_option(grammar, bare_token, all_remaining)]
+    return _short_option_cluster(grammar, bare_token, all_remaining)
+
+
+def _posix_arguments(
+    grammar: search_rules.PosixSearchGrammar, all_arguments: list[str]
+) -> tuple[list[str], list[OptionValue]]:
+    all_positionals: list[str] = []
+    all_options: list[OptionValue] = []
+    all_remaining = collections.deque(all_arguments)
+    while all_remaining:
+        each_token = all_remaining.popleft()
+        bare_token = unquoted_token(each_token)
+        if bare_token == search_rules.END_OF_OPTIONS_TOKEN:
+            all_positionals.extend(all_remaining)
+            break
+        if is_option(each_token):
+            all_options.extend(_options_in_token(grammar, bare_token, all_remaining))
+        else:
+            all_positionals.append(each_token)
+    return all_positionals, all_options
+
+
+def _posix_search_starts(
+    grammar: search_rules.PosixSearchGrammar, all_arguments: list[str]
+) -> list[SearchStart]:
+    all_positionals, all_options = _posix_arguments(grammar, all_arguments)
+    all_option_names = {each_name for each_name, _each_value in all_options}
+    is_recursive_by_option = (
+        grammar.is_recursive_by_default
+        or bool(all_option_names & grammar.all_recurse_options)
+        or any(
+            each_name in grammar.all_recurse_value_options
+            and each_value == search_rules.RECURSE_DIRECTORIES_ACTION
+            for each_name, each_value in all_options
+        )
+    )
+    all_depth_values = [
+        each_value
+        for each_name, each_value in all_options
+        if each_name in grammar.all_depth_options
+    ]
+    has_pattern_positional = grammar.takes_pattern_positional and not (
+        all_option_names & grammar.all_pattern_options
+    )
+    return starts_or_current_directory(
+        all_positionals[1:] if has_pattern_positional else all_positionals,
+        is_recursive_unless_shallow(all_depth_values, is_recursive_by_option),
+    )
+
+
+def _find_search_starts(all_arguments: list[str]) -> list[SearchStart]:
+    all_starting_points: list[str] = []
+    all_remaining = collections.deque(all_arguments)
+    while all_remaining:
+        each_token = all_remaining.popleft()
+        if each_token in walk_flags.ALL_FIND_GLOBAL_OPTION_FLAGS_TAKING_A_VALUE:
+            next_value(all_remaining)
+            continue
+        if each_token in walk_flags.ALL_FIND_GLOBAL_OPTION_FLAGS_WITHOUT_VALUE or (
+            each_token.startswith(walk_flags.FIND_OPTIMIZATION_LEVEL_OPTION_PREFIX)
+        ):
+            continue
+        if each_token in walk_flags.ALL_FIND_EXPRESSION_INTRODUCER_TOKENS or is_option(each_token):
+            break
+        all_starting_points.append(each_token)
+    all_depth_values = [
+        unquoted_token(all_arguments[each_index + 1])
+        for each_index, each_token in enumerate(all_arguments[:-1])
+        if each_token == search_rules.FIND_MAXIMUM_DEPTH_OPTION
+    ]
+    return starts_or_current_directory(
+        all_starting_points, is_recursive_unless_shallow(all_depth_values, True)
+    )
+
+
+def _plain_argument_starts(all_arguments: list[str]) -> list[SearchStart]:
+    return [
+        SearchStart(each_argument, False)
+        for each_argument in all_arguments
+        if not is_option(each_argument)
+    ]
+
+
+_SEARCH_STARTS_BY_PROGRAM: dict[str, Callable[[list[str]], list[SearchStart]]] = {
+    FIND_PROGRAM_NAME: _find_search_starts,
+    **dict.fromkeys(
+        search_rules.ALL_GREP_PROGRAM_NAMES,
+        partial(_posix_search_starts, search_rules.GREP_GRAMMAR),
+    ),
+    **dict.fromkeys(
+        search_rules.ALL_INDEXED_SEARCH_PROGRAM_NAMES,
+        partial(_posix_search_starts, search_rules.INDEXED_SEARCH_GRAMMAR),
+    ),
+    **dict.fromkeys(
+        walk_flags.ALL_UNIX_LS_PROGRAM_BASENAMES,
+        partial(_posix_search_starts, search_rules.UNIX_LS_GRAMMAR),
+    ),
+    search_rules.TREE_PROGRAM_NAME: partial(_posix_search_starts, search_rules.TREE_GRAMMAR),
+    **dict.fromkeys(
+        walk_flags.ALL_POWERSHELL_LISTING_PROGRAM_BASENAMES, powershell_listing_search_starts
+    ),
+    **dict.fromkeys(search_rules.ALL_SELECT_STRING_PROGRAM_NAMES, select_string_search_starts),
+}
+
+
+def _program_search_starts(
+    program_name: str, all_arguments: list[str], is_powershell: bool
+) -> list[SearchStart]:
+    if is_powershell and program_name in walk_flags.ALL_UNIX_LS_PROGRAM_BASENAMES:
+        return powershell_listing_search_starts(all_arguments)
+    search_starts_for = _SEARCH_STARTS_BY_PROGRAM.get(program_name, _plain_argument_starts)
+    return search_starts_for(all_arguments)
+
+
+def _changed_directory(current_directory: str, program_name: str, all_arguments: list[str]) -> str:
+    all_targets = [each_argument for each_argument in all_arguments if not is_option(each_argument)]
+    if all_targets:
+        return joined_path(current_directory, all_targets[0])
+    if program_name in search_rules.ALL_HOME_DEFAULT_CHANGE_DIRECTORY_PROGRAM_NAMES:
+        return search_rules.HOME_DIRECTORY
+    return current_directory
+
+
+def _moved_directory(
+    current_directory: str,
+    all_pushed_directories: list[str],
+    program_name: str,
+    all_arguments: list[str],
+) -> str | None:
+    """Return the folder a ``cd``, ``pushd`` or ``popd`` moves to, else None."""
+    if program_name in search_rules.ALL_POP_DIRECTORY_PROGRAM_NAMES:
+        return all_pushed_directories.pop() if all_pushed_directories else current_directory
+    if program_name not in search_rules.ALL_CHANGE_DIRECTORY_PROGRAM_NAMES:
+        return None
+    if program_name in search_rules.ALL_PUSH_DIRECTORY_PROGRAM_NAMES:
+        all_pushed_directories.append(current_directory)
+    return _changed_directory(current_directory, program_name, all_arguments)
+
+
+def _expanded_program_call(
+    all_segment_tokens: list[str], all_bindings: dict[str, str]
+) -> tuple[str, list[str]]:
+    """Return a segment's lowercase program name and its arguments with variables expanded."""
+    program_name, all_raw_arguments = segment_program_and_arguments(all_segment_tokens)
+    return program_name.lower(), [
+        _expanded_token(each_argument, all_bindings) for each_argument in all_raw_arguments
+    ]
+
+
+def _run_search_starts(
+    all_segments: list[list[str]], cwd: str, is_powershell: bool
+) -> list[SearchStart]:
+    """Return the starts of one tokenization's segments, read in order with their own state."""
+    all_bindings: dict[str, str] = {}
+    current_directory = cwd
+    all_pushed_directories: list[str] = []
+    all_search_starts: list[SearchStart] = []
+    for each_segment in all_segments:
+        assignment = _assignment_from_segment(each_segment)
+        if assignment is not None:
+            all_bindings[assignment[0].lower()] = _expanded_token(assignment[1], all_bindings)
+            continue
+        program_name, all_arguments = _expanded_program_call(each_segment, all_bindings)
+        moved_directory = _moved_directory(
+            current_directory, all_pushed_directories, program_name, all_arguments
+        )
+        if moved_directory is not None:
+            current_directory = moved_directory
+            continue
+        all_search_starts.extend(
+            SearchStart(
+                joined_path(current_directory, each_start.path_text), each_start.is_recursive
+            )
+            for each_start in _program_search_starts(program_name, all_arguments, is_powershell)
+        )
+    return all_search_starts
+
+
+def _segments_in_mode(
+    all_line_tokenizations: list[list[list[str]]], mode_index: int
+) -> list[list[str]]:
+    return [
+        each_segment
+        for each_tokenizations in all_line_tokenizations
+        if each_tokenizations
+        for each_segment, _following_operator in segments_with_following_operator(
+            each_tokenizations[min(mode_index, len(each_tokenizations) - 1)]
+        )
+    ]
+
+
+def _tokenization_runs(command: str) -> list[list[list[str]]]:
+    """Return the segments of each command text once per tokenization mode, lines in order."""
+    all_runs: list[list[list[str]]] = []
+    for each_text in all_wrapped_command_texts(command):
+        all_line_tokenizations = [
+            all_operator_aware_tokenizations(each_line)
+            for each_line in scannable_command_lines(join_line_continuations(each_text))
+            if each_line.strip()
+        ]
+        mode_count = max(map(len, all_line_tokenizations), default=0)
+        all_runs.extend(
+            _segments_in_mode(all_line_tokenizations, each_mode) for each_mode in range(mode_count)
+        )
+    return all_runs
+
+
+def shell_command_search_starts(command: str, cwd: str, is_powershell: bool) -> list[SearchStart]:
+    """Return every search start the shell command's programs name.
+
+    Args:
+        command: The Bash or PowerShell command text the agent is about to run.
+        cwd: The session working directory a relative path resolves from.
+        is_powershell: True for the PowerShell tool, where ``ls`` is ``Get-ChildItem``.
+    """
+    if search_rules.TRANSCRIPT_ROOT_MARKER not in (command + cwd).lower():
+        return []
+    return [
+        each_start
+        for each_run in _tokenization_runs(command)
+        for each_start in _run_search_starts(each_run, cwd, is_powershell)
+    ]

package/hooks/features/bash-dispatchers.md

@@ -10,6 +10,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/gh_global_account_switch_gate.py` denies `gh auth switch`, `gh auth login`, and `gh auth logout` and names the per-command `GH_TOKEN` form to run instead.
 - `blocking/cloud_graphql_gate.py` denies the `gh` commands that call GraphQL (`gh api graphql` with any flags before the endpoint, `gh pr`, `gh issue`, `gh project` and `gh discussion` except `gh pr diff` and `gh pr list --web`, `gh status`, `gh org list`, `gh release list`, `gh release view` with a tag, `gh workflow run` without `--ref`, and a few `repo`, `label`, `search`, `ruleset` and `gist` commands, read past `if`, `!` and command substitutions) and an HTTP client or `python -c` style call to `api.github.com/graphql`, with or without a port, inside a cloud session, where the proxy answers GraphQL with HTTP 403, and names the REST routes to run instead.
 - `blocking/python_windows_invocation_gate.py` denies, on a Windows host, `python`, `python3` or `py` run with `-I` and without `-X utf8`, because `-I` ignores `PYTHONUTF8` and non-ASCII output then stops with `UnicodeEncodeError: 'charmap'`. Under the PowerShell tool it also denies a `python -c "..."` argument that holds `\"`, because PowerShell ends the string at that quote, and names a script file or a single-quoted here-string to use instead.
+- `blocking/transcript_root_search_gate.py` denies a recursive walk or content search that starts at a Claude transcript root, a `projects` folder directly under `.claude`, `.claude-<name>` or `.claude-profiles/<profile>`, with no project folder after it, or with a bare `*` or `**` segment that descends into every project folder. It reads `find`, `grep -r`, `rg`, `ls -R`, `Get-ChildItem -Recurse` or `-Depth`, `Select-String`, and the Grep and Glob tools, and expands variables the command assigns, such as `$p="..."`. A one-level name listing, such as `Get-ChildItem <root> -Directory -Filter "*id*"`, passes. The deny reason names the fix: list the project folders by name, then read the one transcript. The gate reads the root path as the command spells it, so a walk that starts above the root, or a glob that spells the root name or a project-name prefix such as `pro*` or `C--*`, passes.
 - `blocking/bash_post_call_dispatcher.py` runs hosted observers and joins their context output without blocking the call.
 - `advisory/pr_done_reminder.py` adds a pull request checklist after a successful push or pull request creation.
 - `advisory/owned_pr_review_loop.py` adds review-loop instructions after the agent opens a pull request on an owned repository outside the preset list of repositories that run their own automated review: run efficient-review until clean, mark the pull request ready, babysit it, and ship it to merge. It also records the pull request for the session in `owned_pr_session_record.py`.
@@ -23,6 +24,7 @@ This family rewrites a Git Bash command when path conversion would change a revi
 - `blocking/gh_global_account_switch_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools.
 - `blocking/cloud_graphql_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, when `CLAUDE_CODE_REMOTE` is `true`.
 - `blocking/python_windows_invocation_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools. The `-I` check runs only when `os.name` is `nt`.
+- `blocking/transcript_root_search_gate.py` runs inside that dispatcher on `PreToolUse`, matcher `Bash`, timeout `60` seconds, for the Bash and PowerShell tools, and on its own on `PreToolUse`, matcher `Grep|Glob`, timeout `10` seconds in `hooks.json`.
 - `blocking/bash_post_call_dispatcher.py` runs on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds in `hooks.json`.
 - `advisory/pr_done_reminder.py` runs inside that dispatcher on `PostToolUse`, matcher `Bash|PowerShell`, timeout `60` seconds. `ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES` selects `Bash` and `PowerShell`.
 - `advisory/owned_pr_review_loop.py` runs on `PostToolUse`, matcher `Bash|PowerShell|exec_command|shell_command|mcp__.*__(create_pull_request|github_create_pull_request)`, timeout `10` seconds in `hooks.json`. It wakes on `gh pr create`, `gh pr new`, a POST to `gh api repos/<owner>/<repo>/pulls`, a `pull_request.py create` call to the pull request publisher, and an MCP pull request creation. The installer also registers it on Codex `PostToolUse` through `ALL_CODEX_NATIVE_POST_TOOL_USE_HOOK_SCRIPT_NAMES`.
@@ -39,6 +41,7 @@ Preconditions:
 - **Broker gate.** Input is a `claude -p task` command. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_headless_claude_broker_gate.py -q`. The adjacent test observes a denial that names the broker command.
 - **Cloud GraphQL gate.** Input is a `gh api graphql` command with `CLAUDE_CODE_REMOTE=true`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_cloud_graphql_gate.py -q`. The adjacent test observes a denial that names the REST routes, and silence outside a cloud session.
 - **Python Windows invocation gate.** Input is `python -I s.py` on Windows, and a PowerShell `python -c "print(\"x\")"`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_python_windows_invocation_gate.py -q`. The adjacent test observes a denial that names `-X utf8` or the here-string, and a pass for `-IX utf8`, `-I -X utf8`, and the Bash tool.
+- **Transcript root search gate.** Input is `Get-ChildItem $p -Recurse -File -Filter *.jsonl` with `$p` bound to `~/.claude-profiles/work/projects`, and a Grep call whose path is `~/.claude/projects`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_transcript_root_search_gate.py -q`. The adjacent test observes a denial that names the list-then-read fix, and a pass for `Get-ChildItem $p -Directory -Filter "*01WUQeBG*"` and a walk inside one project folder.
 - **Post-call dispatch.** Input is a Bash call that yields hosted context. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_bash_post_call_dispatcher.py -q`. The adjacent test observes a joined context payload and exit code zero.
 - **Pull request reminder.** Input is a completed push or pull request creation. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_pr_done_reminder.py -q`. The adjacent test checks the reminder trigger and checklist verdict.
 - **Owned pull request review loop.** Input is a pull request creation result on an owned repository. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_owned_pr_review_loop.py -q`. The adjacent test observes the review-loop block for owned repositories and silence for the preset and foreign repositories.