claude-dev-env 8.105.2 → 8.106.0

package/docs/rule-guides/filesystem-search.md

@@ -6,7 +6,7 @@ Back to the [rules index](../../rules/index.md).
 
 Scope every search to a project, worktree, package, or narrowing filter. Never start at a filesystem root, drive root, bare home, or share root. Read a known path directly; use scoped `es.exe`, Glob, or Grep for discovery. After `es.exe` Error 8, retry twice before falling back within the same scope. Run one large shell walk at a time.
 
-**Enforcement:** none.
+**Enforcement:** `hooks/blocking/transcript_root_search_gate.py` for Claude transcript roots only. The rest is guidance.
 
 **When this applies:** Any search for files by name, path, extension, size, or date. That includes `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
 
@@ -55,5 +55,6 @@ Issue one shell search at a time when the walk is large. Parallel full-tree sear
 
 ## Search controls
 
-- No hook denies a walk from an unscoped root. The scope invariant above is guidance a reader follows.
+- `hooks/blocking/transcript_root_search_gate.py` denies a recursive walk or content search that starts at a Claude transcript root, such as `~/.claude/projects` or `~/.claude-profiles/<profile>/projects`. List the project folders by name first, then read the one transcript.
+- No hook denies a walk from any other unscoped root. The scope invariant above is guidance a reader follows.
 - For Everything searches that use a project name, run `python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>`. An exact project name becomes its path from `~/.claude/project-paths.json`. The command then starts `es.exe` without a shell. `scripts/setup_project_paths.py` writes the registry.

package/hooks/blocking/test_bash_dispatcher_interpreter_starts.py

@@ -22,7 +22,7 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
 )
 
 
-def test_bash_roster_starts_only_the_msys_rewriter_and_the_four_gates() -> None:
+def test_bash_roster_starts_only_the_msys_rewriter_and_the_five_gates() -> None:
     assert ALL_BASH_HOSTED_HOOK_ENTRIES == (
         BashHostedHookEntry(
             script_relative_path="blocking/msys_rev_path_rewriter.py",
@@ -46,4 +46,8 @@ def test_bash_roster_starts_only_the_msys_rewriter_and_the_four_gates() -> None:
             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/blocking/test_bash_pre_tool_use_dispatcher.py

@@ -274,6 +274,7 @@ def test_should_drop_the_gates_the_shell_guards_mod_holds_while_it_is_on(
         "blocking/msys_rev_path_rewriter.py",
         "blocking/cloud_graphql_gate.py",
         "blocking/python_windows_invocation_gate.py",
+        "blocking/transcript_root_search_gate.py",
     ]
 
 

package/hooks/blocking/test_transcript_root_powershell_starts.py

@@ -0,0 +1,79 @@
+"""Tests for transcript_root_powershell_starts, which reads a cmdlet call's search starts."""
+
+from __future__ import annotations
+
+from blocking.transcript_root_powershell_starts import (
+    powershell_listing_search_starts,
+    select_string_search_starts,
+)
+from blocking.transcript_root_search_starts import SearchStart
+
+
+def test_reads_an_unknown_option_value_as_no_path() -> None:
+    assert powershell_listing_search_starts(["-Recurse", "-ea", "0", "-Filter", "*.jsonl"]) == [
+        SearchStart(".", True)
+    ]
+
+
+def test_splits_a_comma_path_list() -> None:
+    assert powershell_listing_search_starts(["-Path", "a,b"]) == [
+        SearchStart("a", False),
+        SearchStart("b", False),
+    ]
+
+
+def test_lets_depth_zero_override_recurse() -> None:
+    assert powershell_listing_search_starts(["x", "-Recurse", "-Depth", "0"]) == [
+        SearchStart("x", False)
+    ]
+
+
+def test_reads_a_glued_depth_as_recursive() -> None:
+    assert powershell_listing_search_starts(["x", "-Depth:3"]) == [SearchStart("x", True)]
+
+
+def test_reads_a_false_recurse_value_as_one_level() -> None:
+    assert powershell_listing_search_starts(["x", "-Recurse:$false"]) == [SearchStart("x", False)]
+
+
+def test_select_string_search_starts_reads_only_its_named_paths() -> None:
+    assert select_string_search_starts(["-Path", "p/*.jsonl", "-Pattern", "needle"]) == [
+        SearchStart("p/*.jsonl", False)
+    ]
+
+
+def test_reads_recurse_after_a_switch_off_the_list() -> None:
+    assert powershell_listing_search_starts(["x", "-Verbose", "-Recurse"]) == [
+        SearchStart("x", True)
+    ]
+
+
+def test_reads_a_switch_abbreviation_as_its_switch() -> None:
+    assert powershell_listing_search_starts(["x", "-Recu", "-Filter", "*.jsonl"]) == [
+        SearchStart("x", True)
+    ]
+
+
+def test_reads_a_directory_abbreviation_without_taking_the_path() -> None:
+    assert powershell_listing_search_starts(["-Dire", "x"]) == [SearchStart("x", False)]
+
+
+def test_reads_a_depth_abbreviation_as_depth() -> None:
+    assert powershell_listing_search_starts(["x", "-Dep", "2"]) == [SearchStart("x", True)]
+
+
+def test_reads_the_path_after_a_common_parameter_switch() -> None:
+    assert powershell_listing_search_starts(["-Verbose", "x", "-Recurse"]) == [
+        SearchStart("x", True)
+    ]
+    assert powershell_listing_search_starts(["-WhatIf", "x", "-Recurse"]) == [
+        SearchStart("x", True)
+    ]
+
+
+def test_reads_a_short_path_abbreviation_as_path() -> None:
+    assert powershell_listing_search_starts(["-Pa", "x", "-Recurse"]) == [SearchStart("x", True)]
+
+
+def test_reads_an_ambiguous_abbreviation_as_an_option_value() -> None:
+    assert powershell_listing_search_starts(["-De", "2", "x"]) == [SearchStart("x", False)]

package/hooks/blocking/test_transcript_root_search_gate.py

@@ -0,0 +1,180 @@
+"""Tests for transcript_root_search_gate, which stops walks over a Claude transcript root."""
+
+from __future__ import annotations
+
+import json
+from io import StringIO
+from unittest.mock import patch
+
+import pytest
+
+import transcript_root_search_gate as gate
+
+_OVERDUE_SEARCH_COMMAND = (
+    '$p="C:/Users/dev/.claude-profiles/work/projects"; '
+    "Get-ChildItem $p -Recurse -File -Filter *.jsonl | "
+    "Where-Object LastWriteTime -gt (Get-Date).AddDays(-5) | "
+    "Select-String -Pattern 'lock-clock-digit-port' -List"
+)
+_SCOPED_LISTING_COMMAND = (
+    '$p="C:/Users/dev/.claude-profiles/work/projects"; '
+    'Get-ChildItem $p -Directory -Filter "*01WUQeBG*"'
+)
+
+
+def _stdout_from_main(payload: dict[str, object]) -> str:
+    """Return what main() wrote to stdout for one hook payload."""
+    captured_stdout = StringIO()
+    with (
+        patch("sys.stdin", StringIO(json.dumps(payload))),
+        patch("sys.stdout", captured_stdout),
+        patch.object(gate, "log_hook_block"),
+    ):
+        gate.main()
+    return captured_stdout.getvalue()
+
+
+def _shell_payload(tool_name: str, command: str) -> dict[str, object]:
+    return {"tool_name": tool_name, "tool_input": {"command": command}, "cwd": "C:/dev/repo"}
+
+
+def _is_denied(stdout_text: str) -> bool:
+    if not stdout_text.strip():
+        return False
+    return json.loads(stdout_text)["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        _OVERDUE_SEARCH_COMMAND,
+        r"Get-ChildItem C:\Users\dev\.claude\projects -Recurse -Filter *.jsonl",
+        r'gci -Path "$env:USERPROFILE\.claude\projects" -Recurse:$true',
+        r"dir C:\Users\dev\.claude\projects -Depth 3",
+        "$p = '~/.claude/projects'; Get-ChildItem -LiteralPath $p -Recurse",
+        r'Select-String -Path "$HOME\.claude\projects\*\*.jsonl" -Pattern needle',
+        "Get-ChildItem ~/.claude/projects/* -Recurse",
+    ],
+)
+def test_should_deny_a_powershell_walk_over_a_transcript_root(command: str) -> None:
+    assert _is_denied(_stdout_from_main(_shell_payload("PowerShell", command)))
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "find ~/.claude/projects -name '*.jsonl'",
+        "find -L /c/Users/dev/.claude/projects/ -type f",
+        "grep -rn needle ~/.claude-profiles/work/projects/",
+        "grep -Rl needle /home/u/.claude/projects",
+        "rg needle /c/Users/dev/.claude-work/projects",
+        "ls -laR ~/.claude/projects",
+        'p=~/.claude/projects; grep -rl needle "$p"',
+        'export ROOT="$HOME/.claude/projects" && find "${ROOT}" -newer x',
+        "bash -c 'find ~/.claude/projects -name x'",
+        "grep needle ~/.claude/projects/*/*.jsonl",
+    ],
+)
+def test_should_deny_a_bash_walk_over_a_transcript_root(command: str) -> None:
+    assert _is_denied(_stdout_from_main(_shell_payload("Bash", command)))
+
+
+@pytest.mark.parametrize(
+    ("tool_name", "command"),
+    [
+        ("PowerShell", _SCOPED_LISTING_COMMAND),
+        ("PowerShell", r"Get-ChildItem C:\Users\dev\.claude\projects"),
+        ("PowerShell", r"Get-ChildItem C:\Users\dev\.claude\projects\*01WUQeBG*"),
+        ("PowerShell", r"Get-ChildItem C:\Users\dev\.claude\projects\C--dev-repo -Recurse"),
+        ("PowerShell", "Select-String -Path ~/.claude/projects/C--dev-repo/a.jsonl -Pattern x"),
+        ("PowerShell", r"dir C:\Users\dev\.claude\projects -Depth 0"),
+        ("Bash", "find ~/.claude/projects -maxdepth 1 -name '*01WUQeBG*'"),
+        ("Bash", "grep -rn needle ~/.claude/projects/C--dev-repo"),
+        ("Bash", "grep -rn needle ~/.claude/skills"),
+        ("Bash", "grep -n projects notes.txt"),
+        ("Bash", "find . -name projects"),
+        ("Bash", "ls -la ~/.claude/projects"),
+        ("Bash", "rg needle packages/claude-dev-env"),
+    ],
+)
+def test_should_allow_a_scoped_command(tool_name: str, command: str) -> None:
+    assert _stdout_from_main(_shell_payload(tool_name, command)) == ""
+
+
+@pytest.mark.parametrize(
+    "tool_input",
+    [
+        {"pattern": "needle", "path": "C:/Users/dev/.claude/projects"},
+        {"pattern": "needle", "path": "C:\\Users\\dev\\.claude-profiles\\work\\projects\\"},
+        {"pattern": "needle", "path": "/home/u/.claude-work/projects", "glob": "*.jsonl"},
+    ],
+)
+def test_should_deny_a_grep_tool_search_over_a_transcript_root(
+    tool_input: dict[str, str],
+) -> None:
+    payload = {"tool_name": "Grep", "tool_input": tool_input, "cwd": "C:/dev/repo"}
+    assert _is_denied(_stdout_from_main(payload))
+
+
+def test_should_deny_a_grep_tool_search_that_starts_at_a_transcript_root_cwd() -> None:
+    payload = {
+        "tool_name": "Grep",
+        "tool_input": {"pattern": "needle"},
+        "cwd": "C:/Users/dev/.claude/projects",
+    }
+    assert _is_denied(_stdout_from_main(payload))
+
+
+def test_should_allow_a_grep_tool_search_inside_one_project_folder() -> None:
+    payload = {
+        "tool_name": "Grep",
+        "tool_input": {"pattern": "needle", "path": "C:/Users/dev/.claude/projects/C--dev-repo"},
+        "cwd": "C:/dev/repo",
+    }
+    assert _stdout_from_main(payload) == ""
+
+
+@pytest.mark.parametrize(
+    "tool_input",
+    [
+        {"pattern": "**/*.jsonl", "path": "C:/Users/dev/.claude/projects"},
+        {"pattern": "C:/Users/dev/.claude/projects/**/*.jsonl"},
+        {"pattern": "*/*.jsonl", "path": "/home/u/.claude-profiles/work/projects"},
+        {"pattern": "**", "path": "/home/u/.claude/projects"},
+    ],
+)
+def test_should_deny_a_glob_tool_walk_over_a_transcript_root(
+    tool_input: dict[str, str],
+) -> None:
+    payload = {"tool_name": "Glob", "tool_input": tool_input, "cwd": "C:/dev/repo"}
+    assert _is_denied(_stdout_from_main(payload))
+
+
+@pytest.mark.parametrize(
+    "tool_input",
+    [
+        {"pattern": "*01WUQeBG*", "path": "C:/Users/dev/.claude/projects"},
+        {"pattern": "*01WUQeBG*/*.jsonl", "path": "C:/Users/dev/.claude/projects"},
+        {"pattern": "**/*.py", "path": "C:/dev/repo"},
+    ],
+)
+def test_should_allow_a_glob_tool_listing_by_name(tool_input: dict[str, str]) -> None:
+    payload = {"tool_name": "Glob", "tool_input": tool_input, "cwd": "C:/dev/repo"}
+    assert _stdout_from_main(payload) == ""
+
+
+def test_should_name_the_list_then_read_fix_in_the_deny_reason() -> None:
+    stdout_text = _stdout_from_main(_shell_payload("PowerShell", _OVERDUE_SEARCH_COMMAND))
+    deny_reason = json.loads(stdout_text)["hookSpecificOutput"]["permissionDecisionReason"]
+    assert "-Directory -Filter" in deny_reason
+    assert "C:/Users/dev/.claude-profiles/work/projects" in deny_reason
+    assert "read the one transcript" in deny_reason
+
+
+def test_should_stay_quiet_for_another_tool() -> None:
+    payload = {
+        "tool_name": "Read",
+        "tool_input": {"file_path": "C:/Users/dev/.claude/projects"},
+        "cwd": "C:/dev/repo",
+    }
+    assert _stdout_from_main(payload) == ""

package/hooks/blocking/test_transcript_root_search_starts.py

@@ -0,0 +1,85 @@
+"""Tests for transcript_root_search_starts, which reads where a search begins."""
+
+from __future__ import annotations
+
+import pytest
+
+from blocking.transcript_root_search_starts import (
+    SearchStart,
+    file_search_tool_start,
+    joined_path,
+    normalized_path,
+    walked_transcript_root,
+)
+
+
+@pytest.mark.parametrize(
+    ("search_start", "expected_root"),
+    [
+        (SearchStart("~/.claude/projects", True), "~/.claude/projects"),
+        (SearchStart("~/.claude/projects/", True), "~/.claude/projects"),
+        (SearchStart("~/.claude/projects/.", True), "~/.claude/projects"),
+        (SearchStart("~/.claude/projects/C--x/..", True), "~/.claude/projects"),
+        (
+            SearchStart(r"C:\Users\dev\.claude-work\projects", True),
+            "C:/Users/dev/.claude-work/projects",
+        ),
+        (
+            SearchStart("/h/.claude-profiles/work/projects/*/*.jsonl", False),
+            "/h/.claude-profiles/work/projects",
+        ),
+        (SearchStart("~/.claude/projects/**", True), "~/.claude/projects"),
+        (SearchStart("~/.claude/projects/**", False), None),
+        (SearchStart("~/.claude/projects", False), None),
+        (SearchStart("~/.claude/projects/*01WU*", False), None),
+        (SearchStart("~/.claude/projects/C--repo", True), None),
+        (SearchStart("~/.claude/skills", True), None),
+        (SearchStart("~/notes/projects", True), None),
+    ],
+)
+def test_walked_transcript_root_reads_the_root_a_start_walks(
+    search_start: SearchStart, expected_root: str | None
+) -> None:
+    assert walked_transcript_root(search_start) == expected_root
+
+
+def test_normalized_path_folds_quotes_backslashes_and_dot_segments() -> None:
+    assert normalized_path('"C:\\h\\.claude\\projects\\C--x\\..\\"') == "C:/h/.claude/projects"
+
+
+def test_joined_path_reads_a_relative_path_from_the_base_directory() -> None:
+    assert joined_path("/home/u/.claude", "projects") == "/home/u/.claude/projects"
+
+
+def test_joined_path_keeps_an_absolute_path() -> None:
+    assert joined_path("/cwd", "~/.claude/projects") == "~/.claude/projects"
+
+
+def test_file_search_tool_start_reads_grep_as_recursive_from_its_path() -> None:
+    assert file_search_tool_start("Grep", {"path": "/h/.claude/projects"}, "/cwd") == SearchStart(
+        "/h/.claude/projects", True
+    )
+
+
+def test_file_search_tool_start_reads_a_relative_grep_path_from_the_session_directory() -> None:
+    assert file_search_tool_start("Grep", {"path": "projects"}, "/h/.claude") == SearchStart(
+        "/h/.claude/projects", True
+    )
+
+
+def test_file_search_tool_start_reads_grep_with_no_path_from_the_session_directory() -> None:
+    assert file_search_tool_start("Grep", {"pattern": "x"}, "/h/.claude/projects") == (
+        SearchStart("/h/.claude/projects", True)
+    )
+
+
+def test_file_search_tool_start_joins_a_glob_pattern_below_its_path() -> None:
+    assert file_search_tool_start(
+        "Glob", {"pattern": "*/*.jsonl", "path": "C:\\h\\.claude\\projects\\"}, "/cwd"
+    ) == SearchStart("C:/h/.claude/projects/*/*.jsonl", False)
+
+
+def test_file_search_tool_start_keeps_an_absolute_glob_pattern_and_reads_its_recursion() -> None:
+    assert file_search_tool_start("Glob", {"pattern": "/h/.claude/projects/**"}, "/cwd") == (
+        SearchStart("/h/.claude/projects/**", True)
+    )

package/hooks/blocking/test_transcript_root_shell_starts.py

@@ -0,0 +1,131 @@
+"""Tests for transcript_root_shell_starts, which reads where a shell search begins."""
+
+from __future__ import annotations
+
+import pytest
+
+from blocking.transcript_root_search_starts import SearchStart, walked_transcript_root
+from blocking.transcript_root_shell_starts import shell_command_search_starts
+
+ROOT = "C:/Users/dev/.claude/projects"
+
+
+def _walked_roots(command: str, cwd: str = "", is_powershell: bool = False) -> list[str]:
+    return [
+        each_root
+        for each_root in (
+            walked_transcript_root(each_start)
+            for each_start in shell_command_search_starts(command, cwd, is_powershell)
+        )
+        if each_root
+    ]
+
+
+def test_expands_a_variable_the_command_assigns() -> None:
+    all_starts = shell_command_search_starts(
+        f'$p="{ROOT}"; Get-ChildItem $p -Recurse -Filter *.jsonl', "", True
+    )
+    assert SearchStart(ROOT, True) in all_starts
+
+
+def test_reads_a_name_listing_as_one_level() -> None:
+    all_starts = shell_command_search_starts(
+        f'Get-ChildItem {ROOT} -Directory -Filter "*01WUQeBG*"', "", True
+    )
+    assert SearchStart(ROOT, False) in all_starts
+
+
+def test_skips_a_command_that_never_names_a_projects_folder() -> None:
+    assert shell_command_search_starts("grep -r needle /src", "/home/u", False) == []
+
+
+@pytest.mark.parametrize(
+    ("command", "cwd"),
+    [
+        pytest.param(f"grep -rC2 needle {ROOT}", "", id="short-cluster-with-digit"),
+        pytest.param(f"grep -R1 needle {ROOT}", "", id="short-cluster-r-digit"),
+        pytest.param(f"grep -r needle {ROOT}/.", "", id="dot-segment"),
+        pytest.param("cd ~/.claude/projects && grep -r needle", "", id="cd-then-default-path"),
+        pytest.param("cd ~/.claude/projects && grep -rn -C 2 needle", "", id="grep-option-value"),
+        pytest.param("cd ~/.claude/projects && rg -g '*.jsonl' needle", "", id="rg-option-value"),
+        pytest.param("grep -r -e a -e b", "/home/u/.claude/projects", id="grep-pattern-options"),
+        pytest.param("grep -r needle", "/home/u/.claude/projects", id="session-directory"),
+        pytest.param("cd && grep -r needle .claude/projects", "/x", id="bare-cd-goes-home"),
+        pytest.param(f"p={ROOT}; grep -r x $p; p={ROOT}/C--x", "", id="assignment-after-use"),
+        pytest.param(f"grep -d recurse needle {ROOT}", "", id="grep-directories-recurse"),
+        pytest.param(f"grep --directories=recurse needle {ROOT}", "", id="grep-glued-directories"),
+        pytest.param(f"rg needle {ROOT}", "", id="rg-default"),
+        pytest.param(f"rg --files {ROOT}", "", id="rg-files"),
+        pytest.param(f"rg --files -g '*.jsonl' {ROOT}", "", id="rg-files-glob"),
+        pytest.param(f"fd . {ROOT}", "", id="fd"),
+        pytest.param(f"tree {ROOT}", "", id="tree"),
+        pytest.param(f"find {ROOT} -name '*.jsonl'", "", id="find"),
+        pytest.param(f"ls -R {ROOT}", "", id="ls-recursive"),
+        pytest.param(f"cat {ROOT}/*/*.jsonl | grep needle", "", id="cat-every-transcript"),
+        pytest.param(f"pushd {ROOT} && grep -r needle .", "", id="pushd-then-walk"),
+        pytest.param(
+            f"pushd {ROOT} && pushd {ROOT}/C--x && popd && grep -r needle .",
+            "",
+            id="popd-one-level",
+        ),
+    ],
+)
+def test_reads_a_bash_walk_of_the_root(command: str, cwd: str) -> None:
+    assert _walked_roots(command, cwd)
+
+
+@pytest.mark.parametrize(
+    ("command", "cwd"),
+    [
+        pytest.param(f'$P="{ROOT}"; gci $p -Recurse', "", id="variable-case"),
+        pytest.param(
+            '$h="C:/Users/dev"; $p="$h/.claude/projects"; gci $p -Recurse', "", id="chained"
+        ),
+        pytest.param(
+            r"Set-Location C:\Users\dev\.claude\projects; Get-ChildItem -Recurse -Filter *.jsonl",
+            "",
+            id="backslash-set-location",
+        ),
+        pytest.param("Set-Location C:/Users/dev/.claude; gci projects -Recurse", "", id="relative"),
+        pytest.param("Get-ChildItem -Recurse -ea 0 -Filter *.jsonl", ROOT, id="unknown-option"),
+        pytest.param(f"gci C:/x,{ROOT} -Recurse", "", id="comma-path-list"),
+        pytest.param(f"gci {ROOT} -Depth:3", "", id="glued-depth"),
+        pytest.param(f"ls -r {ROOT}", "", id="ls-alias-recurse"),
+        pytest.param(f"ls {ROOT} -Depth 2", "", id="ls-alias-depth"),
+        pytest.param(f"Get-Content {ROOT}/*/*.jsonl | Select-String x", "", id="get-content"),
+    ],
+)
+def test_reads_a_powershell_walk_of_the_root(command: str, cwd: str) -> None:
+    assert _walked_roots(command, cwd, is_powershell=True)
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        pytest.param(f"rg --max-depth 1 needle {ROOT}", id="rg-spaced-max-depth"),
+        pytest.param(f"rg --max-depth=1 needle {ROOT}", id="rg-glued-max-depth"),
+        pytest.param(f"find {ROOT} -maxdepth 1 -type d", id="find-maxdepth"),
+        pytest.param(f"tree -L 1 {ROOT}", id="tree-one-level"),
+        pytest.param(f"ls {ROOT}/**", id="ls-double-star"),
+        pytest.param(f"grep -r needle {ROOT}/C--repo", id="one-project-folder"),
+        pytest.param(f"grep -eremote {ROOT}", id="glued-pattern-is-no-recursion"),
+        pytest.param(f"git status {ROOT}", id="plain-program-on-the-root"),
+        pytest.param(f"p={ROOT}/C--x; grep -r x $p; p={ROOT}", id="assignment-after-scoped-use"),
+        pytest.param(f"pushd {ROOT} && popd && grep -r needle .", id="popd-returns"),
+    ],
+)
+def test_reads_a_scoped_bash_search_as_no_walk(command: str) -> None:
+    assert _walked_roots(command) == []
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        pytest.param(f"gci {ROOT} -Recurse -Depth 0", id="depth-zero-after-recurse"),
+        pytest.param(f"gci {ROOT} -Depth 0 -Recurse", id="depth-zero-before-recurse"),
+        pytest.param(f"ls {ROOT} -ReadOnly", id="ls-alias-switch"),
+        pytest.param(f"Select-String -Path {ROOT}/*01WU*/x.jsonl -Pattern a", id="select-string"),
+    ],
+)
+def test_reads_a_scoped_powershell_search_as_no_walk(command: str) -> None:
+    assert _walked_roots(command, is_powershell=True) == []

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]