claude-dev-env 2.31.1 → 2.33.0

package/hooks/validators/test_run_all_validators_mutation_tool_parity.py

@@ -0,0 +1,249 @@
+"""Behavioral tests for validator coverage across every mutation tool.
+
+The PreToolUse gate has to reach a MultiEdit and a Codex apply_patch the same
+way it reaches a Write and an Edit. Two things carry that: the hooks.json
+matcher the harness dispatches on, and the payload shape the gate reconstructs
+post-edit content from.
+"""
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from hooks_constants.pre_tool_use_dispatcher_constants import (
+    ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES,
+)
+
+from .run_all_validators import run_validators_entrypoint_subprocess
+
+pytestmark = pytest.mark.usefixtures("ephemeral_exempt_off")
+
+HOOKS_JSON_PATH = Path(__file__).resolve().parents[1] / "hooks.json"
+VALIDATORS_RUNNER_COMMAND_MARKER = "validators.run_all_validators"
+MATCHER_TOOL_NAME_SEPARATOR = "|"
+DENY_DECISION_FRAGMENT = '"permissionDecision": "deny"'
+MAGIC_VALUE_VALIDATOR_NAME = "Magic Values"
+
+CLEAN_MODULE_SOURCE = (
+    "def clean_marker() -> int:\n    computed_value = 1\n    return computed_value\n"
+)
+CLEAN_SECOND_MODULE_SOURCE = (
+    "def second_marker() -> int:\n    counted_value = 1\n    return counted_value\n"
+)
+CLEAN_RETURN_LINE = "    return computed_value\n"
+MAGIC_VALUE_RETURN_LINE = "    return computed_value * 199\n"
+CLEAN_REWRITTEN_RETURN_LINE = "    return computed_value + 1\n"
+
+UPDATE_PATCH_TEMPLATE = (
+    "*** Begin Patch\n"
+    "*** Update File: {relative_path}\n"
+    "@@\n"
+    "-{removed_line}"
+    "+{added_line}"
+    "*** End Patch\n"
+)
+ADD_VIOLATING_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n"
+    "*** Add File: added_module.py\n"
+    "+def added_marker() -> int:\n"
+    "+    return 199\n"
+    "*** End Patch\n"
+)
+DELETE_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n*** Delete File: legacy_module.py\n*** End of File\n*** End Patch\n"
+)
+UNPARSEABLE_PATCH_COMMAND = "not a codex patch at all\n"
+TWO_FILE_PATCH_COMMAND = (
+    "*** Begin Patch\n"
+    "*** Update File: first_module.py\n"
+    "@@\n"
+    "-    return computed_value\n"
+    "+    return computed_value + 1\n"
+    "*** Update File: second_module.py\n"
+    "@@\n"
+    "-    return counted_value\n"
+    "+    return counted_value * 199\n"
+    "*** End Patch\n"
+)
+
+
+def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
+    """Drive the real --pre-tool-use entry point with one payload."""
+    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+
+
+def update_patch_command(relative_path: str, added_line: str) -> str:
+    """Build an Update File patch rewriting the module's return line."""
+    return UPDATE_PATCH_TEMPLATE.format(
+        relative_path=relative_path,
+        removed_line=CLEAN_RETURN_LINE,
+        added_line=added_line,
+    )
+
+
+def write_clean_module(target_directory: Path, module_name: str) -> Path:
+    """Write the clean Python module the payloads target."""
+    target_file = target_directory / module_name
+    target_file.write_text(CLEAN_MODULE_SOURCE, encoding="utf-8")
+    return target_file
+
+
+class TestMutationToolRegistration:
+    def test_validators_gate_is_registered_on_every_mutation_tool(self) -> None:
+        hooks_document = json.loads(HOOKS_JSON_PATH.read_text(encoding="utf-8"))
+        all_matchers = [
+            each_group["matcher"]
+            for each_group in hooks_document["hooks"]["PreToolUse"]
+            for each_hook in each_group.get("hooks", [])
+            if VALIDATORS_RUNNER_COMMAND_MARKER in each_hook.get("command", "")
+        ]
+        assert len(all_matchers) == 1, all_matchers
+        assert (
+            set(all_matchers[0].split(MATCHER_TOOL_NAME_SEPARATOR))
+            == ALL_WRITE_EDIT_MULTI_EDIT_APPLY_PATCH_TOOL_NAMES
+        )
+
+
+class TestMultiEditPayloadLane:
+    def test_multi_edit_introducing_a_violation_denies(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "MultiEdit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "edits": [
+                        {
+                            "old_string": CLEAN_RETURN_LINE,
+                            "new_string": MAGIC_VALUE_RETURN_LINE,
+                        }
+                    ],
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_multi_edit_leaving_clean_content_allows(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "clean_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "MultiEdit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "edits": [
+                        {
+                            "old_string": CLEAN_RETURN_LINE,
+                            "new_string": CLEAN_REWRITTEN_RETURN_LINE,
+                        }
+                    ],
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+
+class TestApplyPatchPayloadLane:
+    def test_apply_patch_introducing_a_violation_denies(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("legacy_module.py", MAGIC_VALUE_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_apply_patch_deny_reason_names_the_patched_file(self, tmp_path: Path) -> None:
+        target_file = write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("legacy_module.py", MAGIC_VALUE_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert target_file.name in completed.stdout
+
+    def test_apply_patch_leaving_clean_content_allows(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "clean_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {
+                    "command": update_patch_command("clean_module.py", CLEAN_REWRITTEN_RETURN_LINE)
+                },
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_apply_patch_adding_a_violating_file_denies(self, tmp_path: Path) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": ADD_VIOLATING_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert MAGIC_VALUE_VALIDATOR_NAME in completed.stdout
+
+    def test_apply_patch_deleting_a_file_allows(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "legacy_module.py")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": DELETE_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_unparseable_apply_patch_command_allows(self, tmp_path: Path) -> None:
+        """A patch this lane cannot read is the enforcer's to deny, not this gate's.
+
+        ``code_rules_enforcer`` denies a payload whose patch markers it cannot
+        parse. Both hooks run on the same call and any denial wins, so this lane
+        allows rather than raising a second denial for one cause. Moving that
+        denial out of the enforcer leaves a malformed patch with no reader.
+        """
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": UNPARSEABLE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT not in completed.stdout
+
+    def test_apply_patch_denies_a_violation_in_its_second_file(self, tmp_path: Path) -> None:
+        write_clean_module(tmp_path, "first_module.py")
+        second_file = tmp_path / "second_module.py"
+        second_file.write_text(CLEAN_SECOND_MODULE_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "apply_patch",
+                "tool_input": {"command": TWO_FILE_PATCH_COMMAND},
+                "cwd": str(tmp_path),
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert DENY_DECISION_FRAGMENT in completed.stdout
+        assert second_file.name in completed.stdout

package/hooks/validators/test_run_all_validators_reporting.py

@@ -0,0 +1,66 @@
+"""Tests for the run report run_all_validators renders after a full run.
+
+Timing metrics and the version header are the two pieces of that report. They
+moved out of test_run_all_validators.py so the paired file keeps room for the
+gate behavior it exists to pin.
+"""
+
+import pytest
+
+from .run_all_validators import (
+    add_timing,
+    build_json_output,
+    create_timing_metrics,
+    format_timing_report,
+    print_header,
+)
+
+
+class TestTimingMetrics:
+    def test_create_timing_metrics_empty(self) -> None:
+        metrics = create_timing_metrics({})
+        assert metrics.total_seconds == 0.0
+        assert metrics.validator_times == {}
+
+    def test_create_timing_metrics_with_data(self) -> None:
+        timings = {"Validator A": 1.5, "Validator B": 2.0}
+        metrics = create_timing_metrics(timings)
+        assert metrics.total_seconds == 3.5
+        assert metrics.validator_times == timings
+
+    def test_add_timing_returns_new_instance(self) -> None:
+        metrics1 = create_timing_metrics({})
+        metrics2 = add_timing(metrics1, "Test", 1.5)
+
+        assert metrics1.total_seconds == 0.0
+        assert metrics2.total_seconds == 1.5
+        assert "Test" not in metrics1.validator_times
+        assert metrics2.validator_times["Test"] == 1.5
+
+    def test_format_report_includes_all_timings(self) -> None:
+        metrics = create_timing_metrics({"Fast": 0.1, "Slow": 2.5})
+        report = format_timing_report(metrics)
+
+        assert "Fast" in report
+        assert "Slow" in report
+        assert "2.6" in report
+
+
+class TestVersionHeader:
+    def test_print_header_includes_version(self, capsys: pytest.CaptureFixture[str]) -> None:
+        print_header()
+        captured = capsys.readouterr()
+
+        assert "PRE-PUSH VALIDATOR RESULTS" in captured.out
+        assert "(v" in captured.out
+
+    def test_build_json_output_includes_version(self) -> None:
+        json_output = build_json_output(
+            results=[],
+            metrics=create_timing_metrics({}),
+            include_timing=False,
+        )
+
+        assert "version" in json_output
+        assert "timestamp" in json_output
+        assert isinstance(json_output["version"], str)

package/hooks/validators/test_todo_checks.py

@@ -27,6 +27,7 @@ class TestUntrackedTodos:
         violations = check_untracked_todos(code, "test.py")
         assert len(violations) == 1
         assert "TODO" in violations[0].message
+        assert "remove it from source code and track the work outside the file" in violations[0].message
 
     def test_todo_with_issue_passes(self) -> None:
         code = "# TODO #123: fix this later\ndef foo(): pass"

package/hooks/validators/todo_checks.py

@@ -24,7 +24,7 @@ def check_untracked_todos(source: str, filename: str) -> List[Violation]:
                 Violation(
                     filename,
                     line_num,
-                    "TODO/FIXME without issue reference - add #<issue_number>",
+                    "TODO/FIXME marker found - remove it from source code and track the work outside the file",
                 )
             )
 

package/package.json

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

package/rules/git-workflow.md

@@ -25,13 +25,6 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh` (no ex
    - Before push: `gh pr ready --undo`
    - After review approved: `gh pr ready`
 
-2. **ONE COMMIT PER REVIEW STAGE**: Each review round gets exactly ONE commit
-   - Initial feature: 1 commit
-   - After review #1: 2 commits (initial + review #1 fixes)
-   - After review #2: 3 commits (initial + review #1 fixes + review #2 fixes)
-   - NEVER squash multiple review stages into one commit
-   - NEVER have multiple commits for the same review stage
-
 ## Never Commit Working Documents or Images
 
 **NEVER commit these files to the repo:**
@@ -53,7 +46,6 @@ An image a PR needs as visual evidence is not an exception to that row. Upload i
 2. Create a TodoWrite checklist with one item per comment.
 3. Fix systematically, marking each todo complete.
 4. Reply to each comment inline.
-5. Create one review-fix commit. Do not squash it with the original.
 
 Repair only reported findings, then re-verify after every repair.
 

package/rules/shell-invocation.md

@@ -18,4 +18,4 @@ When a script file's literal body needs `$(...)`, author it with the Write tool,
 
 ## Enforcement
 
-`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes.
+`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes. A quoted heredoc body is dropped for the same reason: the opener forms that quote or escape the delimiter tell bash to expand nothing down to the terminator, so a backtick there is text the file receives. A bare delimiter expands its body and keeps its scan.

package/rules/testing.md

@@ -26,3 +26,7 @@ Tests exercise real behavior, real data, and production code paths. A test that
 ## The File-Level TDD Gate Reads Content
 
 `tdd_enforcer.py` records each candidate test's content hash at every sighting and compares that hash on the next write. A first sighting requires content that differs from HEAD.
+
+## The Gate Reads a Recorded Failing Run First
+
+`hooks/observability/test_failure_recorder.py` runs on every Bash call and records a single unchained pytest run that names a real test file path and reports a failing exit status. It stores the command, that exit status, and the path in the same content-hash store the gate reads. The gate consults that record before its freshness fallback, and honours it while the candidate's content still matches what failed. `content_hash_store.py`'s module docstring holds the full contract.

package/scripts/check.ps1

@@ -25,6 +25,9 @@
 .PARAMETER SkipRuff
     Skip the ruff run.
 
+.PARAMETER CommentPolicyBase
+    Optional git reference used as the comment-policy baseline.
+
 .OUTPUTS
     Per-tool status lines on stdout. Final summary line:
         CHECK: OK
@@ -34,12 +37,14 @@
 param(
     [switch]$SkipTests,
     [switch]$SkipMypy,
-    [switch]$SkipRuff
+    [switch]$SkipRuff,
+    [string]$CommentPolicyBase
 )
 
 $ErrorActionPreference = 'Stop'
 
 $hooksRoot = Resolve-Path (Join-Path $PSScriptRoot '..' 'hooks')
+$repositoryRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '..' '..')
 $blockingRoot = Join-Path $hooksRoot 'blocking'
 $prLoopScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'pr-loop' 'scripts')
 $processTreeScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' 'process-tree' 'scripts')
@@ -47,6 +52,26 @@ $processTreeScriptsRoot = Resolve-Path (Join-Path $PSScriptRoot '..' '_shared' '
 $failedTools = @()
 $firstNonZeroExitCode = 0
 
+function Resolve-CommentPolicyBase {
+    param([string]$ExplicitBase)
+    if ($ExplicitBase) {
+        $resolvedExplicitBase = & git -C $repositoryRoot rev-parse --verify --quiet "${ExplicitBase}^{commit}" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $resolvedExplicitBase) {
+            return $ExplicitBase
+        }
+        throw "Comment-policy baseline '$ExplicitBase' does not resolve in the repository."
+    }
+    foreach ($candidateBase in @('origin/main', 'HEAD^1')) {
+        $resolvedCandidateBase = & git -C $repositoryRoot rev-parse --verify --quiet "${candidateBase}^{commit}" 2>$null
+        if ($LASTEXITCODE -eq 0 -and $resolvedCandidateBase) {
+            return $candidateBase
+        }
+    }
+    throw 'Comment-policy baseline does not resolve to origin/main or HEAD^1.'
+}
+
+$commentPolicyBase = Resolve-CommentPolicyBase -ExplicitBase $CommentPolicyBase
+
 function Invoke-Tool {
     param(
         [string]$Label,
@@ -78,6 +103,15 @@ if (-not $SkipRuff) {
     }
 }
 
+Invoke-Tool -Label 'comment-policy' -Action {
+    Push-Location $prLoopScriptsRoot
+    try {
+        python code_rules_gate.py --base $commentPolicyBase --comment-policy --repo-root $repositoryRoot
+    } finally {
+        Pop-Location
+    }
+}
+
 if (-not $SkipMypy) {
     Invoke-Tool -Label 'mypy' -Action {
         Push-Location $hooksRoot

package/scripts/codex_compat_materializer.py

@@ -62,6 +62,7 @@ codex_hook_dependency_manifest = (
     "hooks/blocking/code_rules_boolean_mustcheck.py",
     "hooks/blocking/code_rules_command_dispatch.py",
     "hooks/blocking/code_rules_comments.py",
+    "hooks/blocking/javascript_comment_scanner.py",
     "hooks/blocking/code_rules_constants_config.py",
     "hooks/blocking/codex_apply_patch.py",
     "hooks/blocking/config/__init__.py",

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -8,6 +8,15 @@ here rather than inline in the modules.
 
 from __future__ import annotations
 
+# The installed tree's own shape is shared with every other reader of it.
+from dev_env_scripts_constants.shared_tree_constants import (  # noqa: F401
+    CLAUDE_CONFIG_DIR_ENV_VAR,
+    PROCESS_TREE_DIRECTORY_NAME,
+    PROCESS_TREE_KILL_MODULE_FILENAME,
+    SCRIPTS_DIRECTORY_NAME,
+    SHARED_PACKAGE_DIRECTORY_NAME,
+)
+
 GROK_BINARY_NAME: str = "grok"
 """Executable name resolved on PATH for the headless grok tier."""
 
@@ -56,19 +65,14 @@ DEFAULT_PING_TIMEOUT_SECONDS: int = 120
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds Claude config."""
 
-CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
 """Environment variable naming the managed Claude config root."""
 
-PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"
 """Filename of the shared process-tree kill helper."""
 
-SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
 """Directory name of the shared install tree under the managed root."""
 
-PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
 """Directory name of the process-tree helper package under ``_shared``."""
 
-SCRIPTS_DIRECTORY_NAME: str = "scripts"
 """Directory name holding Python helpers under a process-tree package."""
 
 MANIFEST_FILENAME: str = ".claude-dev-env-manifest.json"

package/scripts/dev_env_scripts_constants/shared_tree_constants.py

@@ -0,0 +1,17 @@
+"""Constants for resolving directories inside the installed shared tree.
+
+These name the shape of the installed tree itself, not any one worker or
+skill that reads it, so every caller of shared_tree_paths shares them.
+"""
+
+from __future__ import annotations
+
+CLAUDE_CONFIG_DIR_ENV_VAR: str = "CLAUDE_CONFIG_DIR"
+
+SHARED_PACKAGE_DIRECTORY_NAME: str = "_shared"
+
+SCRIPTS_DIRECTORY_NAME: str = "scripts"
+
+PROCESS_TREE_DIRECTORY_NAME: str = "process-tree"
+
+PROCESS_TREE_KILL_MODULE_FILENAME: str = "process_tree_kill.py"

package/scripts/shared_tree_paths.py

@@ -1,11 +1,16 @@
-"""Resolve directories inside the installed shared tree."""
+"""Resolve a scripts directory inside the installed shared tree.
+
+An install can place a managed directory behind a directory junction. Path
+resolution walks that link, so a parent computed from the resolved path
+names the link target's parent, where the shared tree does not sit.
+"""
 
 from __future__ import annotations
 
 from collections.abc import Mapping
 from pathlib import Path
 
-from dev_env_scripts_constants.grok_worker_constants import (
+from dev_env_scripts_constants.shared_tree_constants import (
     CLAUDE_CONFIG_DIR_ENV_VAR,
     PROCESS_TREE_DIRECTORY_NAME,
     PROCESS_TREE_KILL_MODULE_FILENAME,
@@ -14,57 +19,86 @@ from dev_env_scripts_constants.grok_worker_constants import (
 )
 
 
-def _process_tree_scripts_directory(from_root: Path) -> Path:
+def _shared_scripts_directory(from_root: Path, shared_subpackage_name: str) -> Path:
+    """Return the scripts directory one named sub-package holds under a root."""
     return (
         from_root
         / SHARED_PACKAGE_DIRECTORY_NAME
-        / PROCESS_TREE_DIRECTORY_NAME
+        / shared_subpackage_name
         / SCRIPTS_DIRECTORY_NAME
     )
 
 
-def _has_process_tree_kill_module(from_directory: Path) -> bool:
-    return (from_directory / PROCESS_TREE_KILL_MODULE_FILENAME).is_file()
-
-
-def resolve_shared_process_tree_scripts_directory(
+def resolve_shared_scripts_directory(
     module_file: str | Path,
     all_environment: Mapping[str, str],
+    shared_subpackage_name: str,
+    marker_filename: str,
+    anchor_depth: int,
 ) -> Path:
-    """Return the first process-tree scripts directory that holds the kill helper.
+    """Return the first shared scripts directory that holds the marker file.
 
     ::
 
-        scripts dir is a junction; the kill helper sits beside the un-resolved parent
-        ok:   Path(module_file).absolute().parent.parent then the _shared scripts dir
-        flag: Path(module_file).resolve().parents[1] walks the junction and misses it
+        the managed scripts directory is a junction
+        ok:   an un-resolved parent keeps the link side, where _shared sits
+        flag: a resolved parent walks the link and misses _shared entirely
 
-    Tries the un-resolved parent first, then the configured managed root, then
-    the resolved parent. When none hold the helper, return the un-resolved
-    candidate so import failure names a readable path.
+    Tries the un-resolved parent first, then the configured managed root,
+    then the resolved parent. When none holds the marker, returns the
+    un-resolved candidate, so an import failure names a readable path.
 
     Args:
         module_file: Path of the importing module (``__file__``).
         all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+        shared_subpackage_name: Directory under ``_shared`` to resolve.
+        marker_filename: File whose presence marks the right directory.
+        anchor_depth: Parent levels above the module to treat as the root.
 
     Returns:
-        Directory that should hold ``process_tree_kill.py``.
+        Directory that should hold the marker file.
     """
-    un_resolved_candidate = _process_tree_scripts_directory(
-        Path(module_file).absolute().parent.parent
+    module_path = Path(module_file)
+    un_resolved_candidate = _shared_scripts_directory(
+        module_path.absolute().parents[anchor_depth], shared_subpackage_name
     )
     all_candidates = [un_resolved_candidate]
-    configured_root_text = all_environment.get(
-        CLAUDE_CONFIG_DIR_ENV_VAR, ""
-    ).strip()
+    configured_root_text = all_environment.get(CLAUDE_CONFIG_DIR_ENV_VAR, "").strip()
     if configured_root_text:
         all_candidates.append(
-            _process_tree_scripts_directory(Path(configured_root_text))
+            _shared_scripts_directory(Path(configured_root_text), shared_subpackage_name)
         )
     all_candidates.append(
-        _process_tree_scripts_directory(Path(module_file).resolve().parents[1])
+        _shared_scripts_directory(
+            module_path.resolve().parents[anchor_depth], shared_subpackage_name
+        )
     )
     for each_candidate in all_candidates:
-        if _has_process_tree_kill_module(each_candidate):
+        if (each_candidate / marker_filename).is_file():
             return each_candidate
     return un_resolved_candidate
+
+
+def resolve_shared_process_tree_scripts_directory(
+    module_file: str | Path,
+    all_environment: Mapping[str, str],
+) -> Path:
+    """Return the process-tree scripts directory that holds the kill helper.
+
+    Names the process-tree sub-package for a caller sitting one level under
+    the installed root, such as a script in the managed ``scripts`` directory.
+
+    Args:
+        module_file: Path of the importing module (``__file__``).
+        all_environment: Mapping that may hold ``CLAUDE_CONFIG_DIR``.
+
+    Returns:
+        Directory that should hold ``process_tree_kill.py``.
+    """
+    return resolve_shared_scripts_directory(
+        module_file,
+        all_environment,
+        PROCESS_TREE_DIRECTORY_NAME,
+        PROCESS_TREE_KILL_MODULE_FILENAME,
+        1,
+    )