claude-dev-env 8.105.1 → 8.106.0

package/hooks/hooks.json

@@ -152,6 +152,16 @@
           }
         ]
       },
+      {
+        "matcher": "Grep|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/transcript_root_search_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "EnterWorktree",
         "hooks": [

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -83,4 +83,8 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
         script_relative_path="blocking/python_windows_invocation_gate.py",
         applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
     ),
+    BashHostedHookEntry(
+        script_relative_path="blocking/transcript_root_search_gate.py",
+        applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+    ),
 )

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -12,7 +12,7 @@ ALL_BASH_AND_POWERSHELL_TOOL_NAMES = ALL_CONSTANT_BINDINGS["ALL_BASH_AND_POWERSH
 BashHostedHookEntry = ALL_CONSTANT_BINDINGS["BashHostedHookEntry"]
 
 
-def test_roster_hosts_the_five_gates_and_hands_two_to_the_shell_guards_mod() -> None:
+def test_roster_hosts_the_six_gates_and_hands_two_to_the_shell_guards_mod() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -36,4 +36,8 @@ def test_roster_hosts_the_five_gates_and_hands_two_to_the_shell_guards_mod() ->
             script_relative_path="blocking/python_windows_invocation_gate.py",
             applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
         ),
+        BashHostedHookEntry(
+            script_relative_path="blocking/transcript_root_search_gate.py",
+            applicable_tool_names=ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
+        ),
     )

package/hooks/hooks_constants/transcript_root_search_gate_constants.py

@@ -0,0 +1,301 @@
+"""Constants for the gate that stops walks and content searches over a Claude transcript root.
+
+Holds the transcript root pattern and the marker word every root path holds,
+the path parts the gate joins and splits on, the shell assignment and variable
+reference patterns, the directory-change programs, the option grammar of each
+POSIX search program and the PowerShell switches, the Grep and Glob tool names
+and input keys, the hook name the block log records, and the deny message that
+names the list-then-read fix.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+__all__ = [
+    "TRANSCRIPT_ROOT_PATTERN",
+    "TRANSCRIPT_ROOT_MARKER",
+    "PATH_SEPARATOR",
+    "WINDOWS_PATH_SEPARATOR",
+    "CURRENT_DIRECTORY",
+    "POWERSHELL_PATH_LIST_SEPARATOR",
+    "WILDCARD_ONLY_SEGMENT_PATTERN",
+    "RECURSIVE_GLOB_SEGMENT",
+    "ABSOLUTE_PATH_PATTERN",
+    "SHELL_ASSIGNMENT_PATTERN",
+    "SPACED_ASSIGNMENT_NAME_PATTERN",
+    "SPACED_ASSIGNMENT_OPERATOR",
+    "SPACED_ASSIGNMENT_TOKEN_COUNT",
+    "ALL_ASSIGNMENT_PREFIX_WORDS",
+    "SHELL_VARIABLE_SIGIL",
+    "SHELL_VARIABLE_REFERENCE_TEMPLATE",
+    "ALL_CHANGE_DIRECTORY_PROGRAM_NAMES",
+    "ALL_HOME_DEFAULT_CHANGE_DIRECTORY_PROGRAM_NAMES",
+    "ALL_PUSH_DIRECTORY_PROGRAM_NAMES",
+    "ALL_POP_DIRECTORY_PROGRAM_NAMES",
+    "HOME_DIRECTORY",
+    "FIND_MAXIMUM_DEPTH_OPTION",
+    "ALL_SHALLOW_DEPTH_VALUES",
+    "OPTION_PREFIX",
+    "LONG_OPTION_PREFIX",
+    "END_OF_OPTIONS_TOKEN",
+    "GLUED_OPTION_VALUE_SEPARATOR",
+    "RECURSE_DIRECTORIES_ACTION",
+    "PosixSearchGrammar",
+    "ALL_GREP_PROGRAM_NAMES",
+    "GREP_GRAMMAR",
+    "ALL_INDEXED_SEARCH_PROGRAM_NAMES",
+    "INDEXED_SEARCH_GRAMMAR",
+    "UNIX_LS_GRAMMAR",
+    "TREE_PROGRAM_NAME",
+    "TREE_GRAMMAR",
+    "POWERSHELL_TOOL_NAME",
+    "POWERSHELL_DEPTH_OPTION",
+    "POWERSHELL_NON_RECURSIVE_DEPTH",
+    "ALL_POWERSHELL_SWITCH_OPTIONS",
+    "POWERSHELL_GLUED_VALUE_SEPARATOR",
+    "POWERSHELL_MINIMUM_ABBREVIATION_LENGTH",
+    "ALL_POWERSHELL_ABBREVIABLE_OPTIONS",
+    "ALL_SELECT_STRING_PROGRAM_NAMES",
+    "GLOB_TOOL_NAME",
+    "ALL_FILE_SEARCH_TOOL_NAMES",
+    "TOOL_INPUT_PATH_KEY",
+    "TOOL_INPUT_PATTERN_KEY",
+    "TOOL_INPUT_COMMAND_KEY",
+    "PAYLOAD_TOOL_NAME_KEY",
+    "PAYLOAD_TOOL_INPUT_KEY",
+    "PAYLOAD_CWD_KEY",
+    "GATE_HOOK_NAME",
+    "TRANSCRIPT_ROOT_DENY_REASON_TEMPLATE",
+]
+
+TRANSCRIPT_ROOT_PATTERN = re.compile(
+    r"(?:^|/)(?:\.claude|\.claude-profiles/[^/]+|\.claude-[^/]+)/projects(?=/|$)",
+    re.IGNORECASE,
+)
+TRANSCRIPT_ROOT_MARKER = "projects"
+PATH_SEPARATOR = "/"
+WINDOWS_PATH_SEPARATOR = "\\"
+CURRENT_DIRECTORY = "."
+POWERSHELL_PATH_LIST_SEPARATOR = ","
+WILDCARD_ONLY_SEGMENT_PATTERN = re.compile(r"[*?.]*\*[*?.]*")
+RECURSIVE_GLOB_SEGMENT = "**"
+ABSOLUTE_PATH_PATTERN = re.compile(r"^(?:[A-Za-z]:|/|\\|~|\$)")
+
+SHELL_ASSIGNMENT_PATTERN = re.compile(
+    r"^\$?(?:env:)?(?P<name>[A-Za-z_][A-Za-z0-9_]*)=(?P<value>.+)$"
+)
+SPACED_ASSIGNMENT_NAME_PATTERN = re.compile(r"^\$(?:env:)?(?P<name>[A-Za-z_][A-Za-z0-9_]*)$")
+SPACED_ASSIGNMENT_OPERATOR = "="
+SPACED_ASSIGNMENT_TOKEN_COUNT = 3
+ALL_ASSIGNMENT_PREFIX_WORDS: frozenset[str] = frozenset({"export", "local", "declare", "set"})
+SHELL_VARIABLE_SIGIL = "$"
+SHELL_VARIABLE_REFERENCE_TEMPLATE = r"\$(?:\{{{name}\}}|(?:env:)?{name}(?![A-Za-z0-9_]))"
+ALL_CHANGE_DIRECTORY_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"cd", "chdir", "pushd", "set-location", "sl", "push-location"}
+)
+ALL_HOME_DEFAULT_CHANGE_DIRECTORY_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"cd", "chdir", "set-location", "sl"}
+)
+ALL_PUSH_DIRECTORY_PROGRAM_NAMES: frozenset[str] = frozenset({"pushd", "push-location"})
+ALL_POP_DIRECTORY_PROGRAM_NAMES: frozenset[str] = frozenset({"popd", "pop-location"})
+HOME_DIRECTORY = "~"
+
+FIND_MAXIMUM_DEPTH_OPTION = "-maxdepth"
+ALL_SHALLOW_DEPTH_VALUES: frozenset[str] = frozenset({"0", "1"})
+OPTION_PREFIX = "-"
+LONG_OPTION_PREFIX = "--"
+END_OF_OPTIONS_TOKEN = "--"
+GLUED_OPTION_VALUE_SEPARATOR = "="
+RECURSE_DIRECTORIES_ACTION = "recurse"
+
+
+@dataclass(frozen=True)
+class PosixSearchGrammar:
+    """How one POSIX search program reads its options and paths.
+
+    Attributes:
+        is_recursive_by_default: True when the program walks below its paths with no option.
+        all_recurse_options: Options that turn on recursion, such as ``-r`` or ``--recursive``.
+        all_value_letters: Short option letters that take a value, glued or as the next token.
+        all_value_options: Long options that take the next token as their value.
+        all_depth_options: Options whose value limits the depth; a shallow value stops recursion.
+        all_recurse_value_options: Options whose value ``recurse`` turns on recursion.
+        all_pattern_options: Options that supply the pattern or list files with no pattern,
+            so no positional pattern comes first.
+        takes_pattern_positional: True when the first positional is the pattern.
+    """
+
+    is_recursive_by_default: bool
+    all_recurse_options: frozenset[str] = frozenset()
+    all_value_letters: frozenset[str] = frozenset()
+    all_value_options: frozenset[str] = frozenset()
+    all_depth_options: frozenset[str] = frozenset()
+    all_recurse_value_options: frozenset[str] = frozenset()
+    all_pattern_options: frozenset[str] = frozenset()
+    takes_pattern_positional: bool = False
+
+
+ALL_GREP_PROGRAM_NAMES: frozenset[str] = frozenset({"grep", "egrep", "fgrep"})
+GREP_GRAMMAR = PosixSearchGrammar(
+    is_recursive_by_default=False,
+    all_recurse_options=frozenset({"-r", "-R", "--recursive", "--dereference-recursive"}),
+    all_value_letters=frozenset({"e", "f", "m", "A", "B", "C", "d", "D"}),
+    all_value_options=frozenset(
+        {
+            "--regexp",
+            "--file",
+            "--max-count",
+            "--after-context",
+            "--before-context",
+            "--context",
+            "--directories",
+            "--devices",
+            "--include",
+            "--exclude",
+            "--exclude-dir",
+            "--exclude-from",
+            "--label",
+            "--group-separator",
+        }
+    ),
+    all_recurse_value_options=frozenset({"-d", "--directories"}),
+    all_pattern_options=frozenset({"-e", "-f", "--regexp", "--file"}),
+    takes_pattern_positional=True,
+)
+ALL_INDEXED_SEARCH_PROGRAM_NAMES: frozenset[str] = frozenset({"rg", "ag", "ack", "fd", "fdfind"})
+INDEXED_SEARCH_GRAMMAR = PosixSearchGrammar(
+    is_recursive_by_default=True,
+    all_value_letters=frozenset(
+        {"e", "f", "g", "t", "T", "m", "A", "B", "C", "d", "j", "M", "r", "E", "x", "X", "S", "G"}
+    ),
+    all_value_options=frozenset(
+        {
+            "--regexp",
+            "--file",
+            "--glob",
+            "--iglob",
+            "--type",
+            "--type-not",
+            "--type-add",
+            "--max-count",
+            "--after-context",
+            "--before-context",
+            "--context",
+            "--max-depth",
+            "--maxdepth",
+            "--depth",
+            "--threads",
+            "--max-columns",
+            "--max-filesize",
+            "--sort",
+            "--sortr",
+            "--encoding",
+            "--pre",
+            "--pre-glob",
+            "--engine",
+            "--path-separator",
+            "--replace",
+            "--color",
+            "--colors",
+            "--ignore",
+            "--file-search-regex",
+            "--extension",
+            "--exclude",
+            "--exec",
+            "--exec-batch",
+            "--size",
+            "--changed-within",
+            "--changed-before",
+        }
+    ),
+    all_depth_options=frozenset({"-d", "--max-depth", "--maxdepth", "--depth"}),
+    all_pattern_options=frozenset({"-e", "-f", "--regexp", "--file", "--files"}),
+    takes_pattern_positional=True,
+)
+UNIX_LS_GRAMMAR = PosixSearchGrammar(
+    is_recursive_by_default=False,
+    all_recurse_options=frozenset({"-R", "--recursive"}),
+    all_value_letters=frozenset({"I", "w", "T"}),
+    all_value_options=frozenset(
+        {"--ignore", "--hide", "--width", "--tabsize", "--sort", "--format", "--time-style"}
+    ),
+)
+TREE_PROGRAM_NAME = "tree"
+TREE_GRAMMAR = PosixSearchGrammar(
+    is_recursive_by_default=True,
+    all_value_letters=frozenset({"L", "P", "I", "o", "H", "T"}),
+    all_value_options=frozenset({"--filelimit", "--charset", "--sort", "--timefmt"}),
+    all_depth_options=frozenset({"-L"}),
+)
+
+POWERSHELL_TOOL_NAME = "PowerShell"
+POWERSHELL_DEPTH_OPTION = "-depth"
+POWERSHELL_NON_RECURSIVE_DEPTH = "0"
+ALL_POWERSHELL_SWITCH_OPTIONS: frozenset[str] = frozenset(
+    {
+        "-recurse",
+        "-r",
+        "-rec",
+        "-file",
+        "-directory",
+        "-ad",
+        "-af",
+        "-ah",
+        "-ar",
+        "-as",
+        "-force",
+        "-name",
+        "-hidden",
+        "-system",
+        "-readonly",
+        "-followsymlink",
+        "-list",
+        "-simplematch",
+        "-casesensitive",
+        "-notmatch",
+        "-allmatches",
+        "-quiet",
+        "-raw",
+        "-noemphasis",
+        "-wait",
+        "-verbose",
+        "-vb",
+        "-debug",
+        "-db",
+        "-whatif",
+        "-wi",
+        "-confirm",
+        "-cf",
+        "-usetransaction",
+        "-usetx",
+    }
+)
+POWERSHELL_GLUED_VALUE_SEPARATOR = ":"
+POWERSHELL_MINIMUM_ABBREVIATION_LENGTH = 3
+ALL_POWERSHELL_ABBREVIABLE_OPTIONS: frozenset[str] = ALL_POWERSHELL_SWITCH_OPTIONS | frozenset(
+    {POWERSHELL_DEPTH_OPTION, "-path", "-literalpath", "-filter", "-include", "-exclude"}
+)
+ALL_SELECT_STRING_PROGRAM_NAMES: frozenset[str] = frozenset({"select-string", "sls"})
+
+GLOB_TOOL_NAME = "Glob"
+ALL_FILE_SEARCH_TOOL_NAMES: frozenset[str] = frozenset({"Grep", GLOB_TOOL_NAME})
+TOOL_INPUT_PATH_KEY = "path"
+TOOL_INPUT_PATTERN_KEY = "pattern"
+TOOL_INPUT_COMMAND_KEY = "command"
+PAYLOAD_TOOL_NAME_KEY = "tool_name"
+PAYLOAD_TOOL_INPUT_KEY = "tool_input"
+PAYLOAD_CWD_KEY = "cwd"
+
+GATE_HOOK_NAME = "transcript_root_search_gate.py"
+
+TRANSCRIPT_ROOT_DENY_REASON_TEMPLATE = (
+    "BLOCKED: this call walks or searches every transcript under `{root}`. "
+    "A Claude transcript root holds thousands of JSONL session files, so a "
+    "recursive walk or content search there runs for minutes and times out. "
+    "Scope the search: list the project folders by name first, for example "
+    '`Get-ChildItem "{root}" -Directory -Filter "*<session id fragment>*"` or '
+    '`Glob(pattern="*<session id fragment>*", path="{root}")`, then read the one '
+    "transcript in the matching folder, or search inside that one folder."
+)

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.105.1",
+    "version": "8.106.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/dev_env_scripts_constants/account_broker_constants.py

@@ -392,15 +392,27 @@ def _unreadable_text(reading: Reading) -> str:
     return f"{reading.account.name} ({reading.unread_reason})"
 
 
-def _wait_reason(all_unreadable_names: Sequence[str], is_every_account_unreadable: bool, soonest: _RetryTime) -> str:
+def _room_text(reading: Reading, is_spent: bool) -> str:
+    if is_spent or reading.meters is None:
+        return f"{reading.account.name} spent"
+    percent_left = reading.meters.tightest_percent_left
+    if percent_left is None:
+        return f"{reading.account.name} percent left unread"
+    return f"{reading.account.name} {percent_left:g}% left"
+
+
+def _wait_reason(
+    all_room_texts: Sequence[str], all_unreadable_names: Sequence[str], is_every_account_unreadable: bool, soonest: _RetryTime
+) -> str:
     next_event = "reset" if soonest.is_known_reset else "check"
     next_text = f"next {next_event} at {utc_time_text(soonest.at)}"
+    room_text = f" ({', '.join(all_room_texts)})" if all_room_texts else ""
     if not all_unreadable_names:
-        return f"no account has room; {next_text}"
+        return f"no account has room{room_text}; {next_text}"
     unreadable_text = ", ".join(all_unreadable_names)
     if is_every_account_unreadable:
         return f"no account meter could be read ({unreadable_text}); {next_text}"
-    return f"no readable account has room; meter unreadable for {unreadable_text}; {next_text}"
+    return f"no readable account has room{room_text}; meter unreadable for {unreadable_text}; {next_text}"
 
 
 def _wait_decision(
@@ -423,5 +435,11 @@ def _wait_decision(
         for each_reading in all_readings
         if each_reading.meters is None and each_reading.account not in all_spent_accounts
     ]
+    all_room_texts = [
+        _room_text(each_reading, each_reading.account in all_spent_accounts)
+        for each_reading in all_readings
+        if each_reading.meters is not None or each_reading.account in all_spent_accounts
+    ]
     is_every_account_unreadable = len(all_unreadable_names) == len(all_readings)
-    return Decision("wait", None, soonest.at, _wait_reason(all_unreadable_names, is_every_account_unreadable, soonest), "wait")
+    reason = _wait_reason(all_room_texts, all_unreadable_names, is_every_account_unreadable, soonest)
+    return Decision("wait", None, soonest.at, reason, "wait")

package/scripts/policy_lint/config/constants.py

@@ -86,6 +86,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/resolve_thread_reply_gate.py",
     "blocking/turn_review_gate.py",
     "blocking/wakeup_cap_gate.py",
+    "blocking/transcript_root_search_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/test_account_broker.py

@@ -91,7 +91,7 @@ def test_should_name_the_unread_account_and_its_reason_when_no_account_has_room(
 
     assert decision.action == "wait"
     assert decision.reason == (
-        "no readable account has room; meter unreadable for codex-3 (codex app-server failed: timed out); "
+        "no readable account has room (codex-4 0% left); meter unreadable for codex-3 (codex app-server failed: timed out); "
         "next check at 2026-10-03T01:00:00+00:00"
     )
     assert payload[0]["unread_reason"] == "codex app-server failed: timed out"
@@ -542,21 +542,21 @@ _EV_CLAUDE = _account("ev", Product.CLAUDE)
         pytest.param(
             (Reading(_MAIN_CLAUDE, _meters(5, 50, short_reset=NOW + timedelta(minutes=30))), Reading(_EV_CLAUDE, None)),
             {},
-            "no readable account has room; meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
+            "no readable account has room (main 5% left); meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
             NOW + timedelta(minutes=30),
             id="unreadable-beside-a-reset-before-the-check",
         ),
         pytest.param(
             (Reading(_MAIN_CLAUDE, _meters(5, 50, short_reset=NOW + timedelta(hours=2))), Reading(_EV_CLAUDE, None)),
             {},
-            "no readable account has room; meter unreadable for ev; next check at 2026-10-03T01:00:00+00:00",
+            "no readable account has room (main 5% left); meter unreadable for ev; next check at 2026-10-03T01:00:00+00:00",
             NOW + timedelta(hours=1),
             id="unreadable-beside-a-reset-after-the-check",
         ),
         pytest.param(
             (Reading(_MAIN_CLAUDE, _meters(80, 80)), Reading(_EV_CLAUDE, None)),
             {_MAIN_CLAUDE: NOW + timedelta(minutes=30)},
-            "no readable account has room; meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
+            "no readable account has room (main spent); meter unreadable for ev; next reset at 2026-10-03T00:30:00+00:00",
             NOW + timedelta(minutes=30),
             id="unreadable-beside-a-spent-account",
         ),
@@ -566,17 +566,31 @@ _EV_CLAUDE = _account("ev", Product.CLAUDE)
                 Reading(_EV_CLAUDE, _meters(5, 80, short_reset=NOW + timedelta(hours=3))),
             ),
             {},
-            "no account has room; next reset at 2026-10-03T02:00:00+00:00",
+            "no account has room (main 5% left, ev 5% left); next reset at 2026-10-03T02:00:00+00:00",
             NOW + timedelta(hours=2),
             id="every-meter-read-with-known-resets",
         ),
         pytest.param(
             (Reading(_MAIN_CLAUDE, Meters(5, None, 50, None)),),
             {},
-            "no account has room; next check at 2026-10-03T01:00:00+00:00",
+            "no account has room (main 5% left); next check at 2026-10-03T01:00:00+00:00",
             NOW + timedelta(hours=1),
             id="every-meter-read-without-a-known-reset",
         ),
+        pytest.param(
+            (),
+            {},
+            "no account has room; next check at 2026-10-03T01:00:00+00:00",
+            NOW + timedelta(hours=1),
+            id="no-account-in-the-roster",
+        ),
+        pytest.param(
+            (Reading(_MAIN_CLAUDE, Meters(None, None, None, None)),),
+            {},
+            "no account has room (main percent left unread); next check at 2026-10-03T01:00:00+00:00",
+            NOW + timedelta(hours=1),
+            id="meter-read-without-a-percent",
+        ),
     ),
 )
 def test_should_name_what_the_broker_knows_in_the_wait_reason(