claude-dev-env 2.26.0 → 2.28.0

package/docs/codex-compatibility.md

@@ -50,6 +50,25 @@ Limits:
 
 - The installer skips Codex `hooks.json` for now. Wire it by hand.
 
+## Luna fast-mode guard
+
+`hooks/blocking/luna_fast_mode_gate.py` serves Claude and Codex. Codex reads its own `hooks.json`, so add this `PreToolUse` group to that file. Replace `<CODEX_HOOKS_ROOT>` with the directory that holds the shipped hook:
+
+```json
+{
+  "matcher": "Agent|Task|multi_agent_v1__spawn_agent",
+  "hooks": [
+    {
+      "type": "command",
+      "command": "python <CODEX_HOOKS_ROOT>/blocking/luna_fast_mode_gate.py",
+      "timeout": 10
+    }
+  ]
+}
+```
+
+The guard requires exact `fast` for Luna spawns through `Agent` and `Task`. Native Codex `multi_agent_v1__spawn_agent` accepts exact `fast` or `priority`. Other models and tools pass through.
+
 ## Roots and safety
 
 Both roots are caller-supplied. The tool never writes to `.agents` or `CODEX_HOME` automatically; pass those locations explicitly when desired. No personal paths or secrets are embedded in the package.

package/hooks/blocking/luna_fast_mode_gate.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""PreToolUse gate: deny Luna spawns that use an unsupported service tier."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Mapping, TextIO
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+from hooks_constants.luna_fast_mode_gate_constants import (  # noqa: E402
+    ALL_SPAWN_TOOL_NAMES,
+    CALLING_HOOK_NAME,
+    CODEX_AGENT_TOOL_NAME,
+    DENY_ADDITIONAL_CONTEXT,
+    DENY_PREVIEW_TEMPLATE,
+    DENY_REASON,
+    FAST_SERVICE_TIER,
+    HOOK_EVENT_NAME,
+    LUNA_MODEL_ALIAS,
+    MAXIMUM_PREVIEW_FIELD_LENGTH,
+    MODEL_FIELD_NAME,
+    MODEL_SEGMENT_SPLIT_PATTERN,
+    PRIORITY_SERVICE_TIER,
+    SERVICE_TIER_FIELD_NAME,
+    TOOL_INPUT_FIELD_NAME,
+    TOOL_NAME_FIELD_NAME,
+)
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+
+
+def _model_names_the_luna_tier(model_identifier: str) -> bool:
+    """Report whether a model string names the Luna tier.
+
+    Args:
+        model_identifier: The spawn's ``model`` string.
+
+    Returns:
+        True when a model segment reads ``luna`` in any letter case; False
+        for another tier.
+    """
+    all_segments = MODEL_SEGMENT_SPLIT_PATTERN.split(model_identifier.strip().lower())
+    return LUNA_MODEL_ALIAS in all_segments
+
+
+def _is_service_tier_allowed(tool_name: object, service_tier: object) -> bool:
+    if service_tier == FAST_SERVICE_TIER:
+        return True
+    return (
+        tool_name == CODEX_AGENT_TOOL_NAME
+        and service_tier == PRIORITY_SERVICE_TIER
+    )
+
+
+def _denied_spawn_details(
+    all_payload_by_field: Mapping[str, object],
+) -> tuple[str, object] | None:
+    """Return model and service tier for a Luna spawn that must be denied.
+
+    Args:
+        all_payload_by_field: The parsed PreToolUse payload.
+
+    Returns:
+        The model and service tier for an invalid Luna spawn; None otherwise.
+    """
+    tool_name = all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "")
+    if tool_name not in ALL_SPAWN_TOOL_NAMES:
+        return None
+    tool_input = all_payload_by_field.get(TOOL_INPUT_FIELD_NAME, {})
+    if not isinstance(tool_input, dict):
+        return None
+    model_identifier = tool_input.get(MODEL_FIELD_NAME)
+    if not isinstance(model_identifier, str):
+        return None
+    if not _model_names_the_luna_tier(model_identifier):
+        return None
+    service_tier = tool_input.get(SERVICE_TIER_FIELD_NAME)
+    if _is_service_tier_allowed(tool_name, service_tier):
+        return None
+    return model_identifier, service_tier
+
+
+def _build_denial_preview(model_identifier: str, service_tier: object) -> str:
+    """Build a bounded preview for the block log without recording the prompt.
+
+    Args:
+        model_identifier: The Luna model string.
+        service_tier: The supplied service tier value.
+
+    Returns:
+        A bounded preview naming only the model and service tier fields.
+    """
+    model_text = model_identifier[:MAXIMUM_PREVIEW_FIELD_LENGTH]
+    service_tier_text = str(service_tier)[:MAXIMUM_PREVIEW_FIELD_LENGTH]
+    return DENY_PREVIEW_TEMPLATE.format(
+        model_text=model_text,
+        service_tier_text=service_tier_text,
+    )
+
+
+def _emit_denial(
+    decision_stream: TextIO,
+    all_payload_by_field: Mapping[str, object],
+    model_identifier: str,
+    service_tier: object,
+) -> None:
+    """Log the denied spawn and write the PreToolUse deny payload.
+
+    Args:
+        decision_stream: Writable stream for the JSON decision.
+        all_payload_by_field: The parsed PreToolUse payload.
+        model_identifier: The denied Luna model string.
+        service_tier: The invalid service tier value.
+    """
+    denial = {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": "deny",
+            "permissionDecisionReason": DENY_REASON,
+            "additionalContext": DENY_ADDITIONAL_CONTEXT,
+        }
+    }
+    log_hook_block(
+        calling_hook_name=CALLING_HOOK_NAME,
+        hook_event=HOOK_EVENT_NAME,
+        block_reason=DENY_REASON,
+        tool_name=str(all_payload_by_field.get(TOOL_NAME_FIELD_NAME, "")),
+        offending_input_preview=_build_denial_preview(model_identifier, service_tier),
+    )
+    decision_stream.write(json.dumps(denial) + "\n")
+    decision_stream.flush()
+
+
+def main() -> None:
+    """Read the PreToolUse payload and deny an invalid Luna spawn."""
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        sys.exit(0)
+    denied_details = _denied_spawn_details(hook_payload)
+    if denied_details is None:
+        sys.exit(0)
+    denied_model, denied_service_tier = denied_details
+    _emit_denial(
+        sys.stdout,
+        hook_payload,
+        denied_model,
+        denied_service_tier,
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_luna_fast_mode_gate.py

@@ -0,0 +1,211 @@
+"""Behavior tests for the Codex Luna fast-mode spawn gate."""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import subprocess
+import sys
+from typing import Any
+from unittest import mock
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+_HOOKS_TREE = _HOOK_DIR.parent
+for each_path in (str(_HOOK_DIR), str(_HOOKS_TREE)):
+    if each_path not in sys.path:
+        sys.path.insert(0, each_path)
+
+hook_spec = importlib.util.spec_from_file_location(
+    "luna_fast_mode_gate",
+    _HOOK_DIR / "luna_fast_mode_gate.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+from hooks_constants.luna_fast_mode_gate_constants import (  # noqa: E402
+    AGENT_TOOL_NAME,
+    CALLING_HOOK_NAME,
+    CODEX_AGENT_TOOL_NAME,
+    FAST_SERVICE_TIER,
+    TASK_TOOL_NAME,
+)
+
+_MODEL_ID = "gpt-5.6-luna"
+_NON_LUNA_MODEL_ID = "gpt-5.6-sol"
+_UNRELATED_TOOL_NAME = "Write"
+_SERVICE_TIER_FIELD_NAME = "service_tier"
+_MODEL_FIELD_NAME = "model"
+_DENY_DECISION = "deny"
+
+
+def _spawn_payload(
+    *,
+    tool_name: str = AGENT_TOOL_NAME,
+    model: object = _MODEL_ID,
+    service_tier: object = None,
+    include_service_tier: bool = True,
+) -> dict[str, Any]:
+    """Build one PreToolUse payload for a spawn surface."""
+    tool_input: dict[str, object] = {
+        _MODEL_FIELD_NAME: model,
+    }
+    if include_service_tier:
+        tool_input[_SERVICE_TIER_FIELD_NAME] = service_tier
+    return {"tool_name": tool_name, "tool_input": tool_input}
+
+
+def _run_main(payload: object) -> str:
+    """Run the production hook and return its stdout."""
+    with mock.patch("sys.stdin", io.StringIO(json.dumps(payload))):
+        with mock.patch("sys.stdout", new_callable=io.StringIO) as captured_stdout:
+            try:
+                hook_module.main()
+            except SystemExit:
+                pass
+            return captured_stdout.getvalue()
+
+
+def _decision(payload: object) -> str:
+    """Return the hook decision for a payload."""
+    return json.loads(_run_main(payload))["hookSpecificOutput"]["permissionDecision"]
+
+
+def test_blocks_luna_without_fast_for_headless_and_in_session_surfaces() -> None:
+    all_tool_names = (AGENT_TOOL_NAME, TASK_TOOL_NAME, CODEX_AGENT_TOOL_NAME)
+    for each_tool_name in all_tool_names:
+        payload = _spawn_payload(tool_name=each_tool_name, service_tier="flex")
+        assert _decision(payload) == _DENY_DECISION
+
+
+def test_allows_luna_with_exact_fast_service_tier() -> None:
+    for each_tool_name in (AGENT_TOOL_NAME, TASK_TOOL_NAME, CODEX_AGENT_TOOL_NAME):
+        payload = _spawn_payload(
+            tool_name=each_tool_name,
+            service_tier=FAST_SERVICE_TIER,
+        )
+        assert _run_main(payload) == ""
+
+
+def test_allows_luna_with_native_priority_service_tier() -> None:
+    payload = _spawn_payload(
+        tool_name=CODEX_AGENT_TOOL_NAME,
+        service_tier="priority",
+    )
+    assert _run_main(payload) == ""
+
+
+def test_blocks_luna_with_priority_for_agent_and_task_surfaces() -> None:
+    for each_tool_name in (AGENT_TOOL_NAME, TASK_TOOL_NAME):
+        payload = _spawn_payload(
+            tool_name=each_tool_name,
+            service_tier="priority",
+        )
+        assert _decision(payload) == _DENY_DECISION
+
+
+def test_blocks_missing_and_non_string_service_tier() -> None:
+    assert _decision(_spawn_payload(include_service_tier=False)) == _DENY_DECISION
+    assert _decision(_spawn_payload(service_tier=None)) == _DENY_DECISION
+    assert _decision(_spawn_payload(service_tier=True)) == _DENY_DECISION
+
+
+def test_blocks_default_and_wrong_case_fast_service_tiers() -> None:
+    assert _decision(_spawn_payload(service_tier="default")) == _DENY_DECISION
+    assert _decision(_spawn_payload(service_tier="FAST")) == _DENY_DECISION
+
+
+def test_allows_non_luna_and_unrelated_tool_payloads() -> None:
+    assert _run_main(_spawn_payload(model=_NON_LUNA_MODEL_ID)) == ""
+    assert _run_main(
+        _spawn_payload(tool_name=_UNRELATED_TOOL_NAME, service_tier="flex")
+    ) == ""
+
+
+def test_recognizes_case_insensitive_luna_model_segments() -> None:
+    assert _decision(_spawn_payload(model="GPT-5.6-LUNA", service_tier="flex")) == (
+        _DENY_DECISION
+    )
+    assert _run_main(_spawn_payload(model="gpt-5.6-lunacy", service_tier="flex")) == ""
+
+
+def test_malformed_outer_payload_allows() -> None:
+    assert _run_main({"tool_name": AGENT_TOOL_NAME}) == ""
+    assert _run_main({"tool_name": AGENT_TOOL_NAME, "tool_input": []}) == ""
+    assert _run_main("not an object") == ""
+    assert _run_main({"tool_name": AGENT_TOOL_NAME, "tool_input": {_MODEL_FIELD_NAME: 7}}) == ""
+
+
+def test_deny_payload_and_log_do_not_include_a_prompt() -> None:
+    payload = _spawn_payload(service_tier="default")
+    with mock.patch.object(hook_module, "log_hook_block") as recorded_block:
+        output = _run_main(payload)
+    parsed_output = json.loads(output)
+    assert parsed_output["hookSpecificOutput"]["permissionDecision"] == _DENY_DECISION
+    assert recorded_block.call_args.kwargs["calling_hook_name"] == CALLING_HOOK_NAME
+    assert "prompt" not in recorded_block.call_args.kwargs["offending_input_preview"]
+
+
+def test_hooks_json_registers_all_spawn_surfaces() -> None:
+    hooks_configuration = json.loads(
+        (_HOOKS_TREE / "hooks.json").read_text(encoding="utf-8")
+    )
+    matching_groups = [
+        each_group
+        for each_group in hooks_configuration["hooks"]["PreToolUse"]
+        if CALLING_HOOK_NAME
+        in " ".join(each_hook["command"] for each_hook in each_group["hooks"])
+    ]
+    assert len(matching_groups) == 1
+    assert matching_groups[0]["matcher"] == (
+        f"{AGENT_TOOL_NAME}|{TASK_TOOL_NAME}|{CODEX_AGENT_TOOL_NAME}"
+    )
+    registered_command = matching_groups[0]["hooks"][0]["command"]
+    assert registered_command.endswith(
+        f"/hooks/blocking/{CALLING_HOOK_NAME}"
+    )
+    assert (_HOOKS_TREE / "blocking" / CALLING_HOOK_NAME).is_file()
+
+
+def test_registered_command_runs_under_windows_cmd_for_allow_and_deny() -> None:
+    hooks_configuration = json.loads(
+        (_HOOKS_TREE / "hooks.json").read_text(encoding="utf-8")
+    )
+    matching_group = next(
+        each_group
+        for each_group in hooks_configuration["hooks"]["PreToolUse"]
+        if CALLING_HOOK_NAME
+        in " ".join(each_hook["command"] for each_hook in each_group["hooks"])
+    )
+    registered_command = matching_group["hooks"][0]["command"]
+    assert registered_command.startswith("python ")
+    command_line = registered_command.replace(
+        "${CLAUDE_PLUGIN_ROOT}",
+        str(_HOOKS_TREE.parent).replace("\\", "/"),
+    )
+
+    for each_service_tier, expected_output in (
+        (FAST_SERVICE_TIER, ""),
+        ("flex", _DENY_DECISION),
+    ):
+        completed_process = subprocess.run(
+            command_line,
+            input=json.dumps(_spawn_payload(service_tier=each_service_tier)),
+            capture_output=True,
+            shell=True,
+            text=True,
+            check=False,
+        )
+        assert completed_process.returncode == 0, completed_process.stderr
+        if expected_output == "":
+            assert completed_process.stdout == ""
+        else:
+            assert (
+                json.loads(completed_process.stdout)["hookSpecificOutput"][
+                    "permissionDecision"
+                ]
+                == expected_output
+            )

package/hooks/hooks.json

@@ -77,6 +77,16 @@
           }
         ]
       },
+      {
+        "matcher": "Agent|Task|multi_agent_v1__spawn_agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/luna_fast_mode_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "ScheduleWakeup|CronCreate",
         "hooks": [
@@ -149,11 +159,6 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/session_env_cleanup.py",
             "timeout": 10
           },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/untracked_repo_detector.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/gh_pr_author_session_cleanup.py",

package/hooks/hooks_constants/AGENTS.md

@@ -45,7 +45,7 @@ Shared constant modules imported by hooks throughout the `hooks/` tree. Each fil
 | `local_identity.py` | Loader for local machine values: NAS host, ssh user, and ssh port the ssh enforcer guards (`CLAUDE_NAS_*` / `~/.claude/local-identity.json` with placeholder defaults), the PII commit-scan exempt-repo slug set (`CLAUDE_PII_EXEMPT_REPOS` / `pii_exempt_repositories`), and the per-repository allowlisted-values mapping (`pii_allowlisted_values`, keyed by owner/repo slug) read from the git-ignored local file whose path `CLAUDE_LOCAL_IDENTITY_PATH` may point elsewhere; also composes the ssh enforcer's two deny messages that quote the NAS values |
 | `messages.py` | Short user-facing notice strings shown when a Stop hook redirects agent behavior |
 | `multi_edit_reconstruction.py` | `apply_edits()` / `edits_for_tool()` — shared helpers that reconstruct the post-edit content of an Edit or MultiEdit, imported by the blockers that judge post-edit content |
-| `mypy_integration_constants.py` | Path markers (``.git``, ``.py``, ``pyproject.toml``) for mypy project-root resolution |
+| `mypy_integration_constants.py` | Path markers (``.git``, ``.py``, ``pyproject.toml``) for mypy project-root resolution, plus detached-file `--follow-imports=skip` flags, subprocess timeout, and timeout skip message |
 | `mypy_validator_cache_constants.py` | Cache paths and tunables for the mypy_validator per-session caches |
 | `nas_ssh_binary_enforcer_constants.py` | Bash tool name, ssh-family basenames, OpenSSH binary path suffixes, and the batch-mode pattern for the NAS ssh binary enforcer; segment helpers come from `shell_command_segments.py` |
 | `open_questions_in_plans_blocker_constants.py` | Patterns for detecting unresolved open questions in plan documents |

package/hooks/hooks_constants/luna_fast_mode_gate_constants.py

@@ -0,0 +1,45 @@
+"""Constants for the Codex Luna fast-mode spawn gate.
+
+The gate checks the model and service tier fields on Agent, Task, and native
+Codex multi-agent spawn calls. Agent and Task require exact ``fast``. Native
+Codex accepts exact ``fast`` or ``priority`` for Luna models.
+"""
+
+from __future__ import annotations
+
+import re
+
+AGENT_TOOL_NAME: str = "Agent"
+TASK_TOOL_NAME: str = "Task"
+CODEX_AGENT_TOOL_NAME: str = "multi_agent_v1__spawn_agent"
+ALL_SPAWN_TOOL_NAMES: frozenset[str] = frozenset(
+    {AGENT_TOOL_NAME, TASK_TOOL_NAME, CODEX_AGENT_TOOL_NAME}
+)
+
+LUNA_MODEL_ALIAS: str = "luna"
+FAST_SERVICE_TIER: str = "fast"
+PRIORITY_SERVICE_TIER: str = "priority"
+MODEL_SEGMENT_SPLIT_PATTERN: re.Pattern[str] = re.compile(r"[^a-z0-9]+")
+
+TOOL_NAME_FIELD_NAME: str = "tool_name"
+TOOL_INPUT_FIELD_NAME: str = "tool_input"
+MODEL_FIELD_NAME: str = "model"
+SERVICE_TIER_FIELD_NAME: str = "service_tier"
+
+CALLING_HOOK_NAME: str = "luna_fast_mode_gate.py"
+HOOK_EVENT_NAME: str = "PreToolUse"
+
+DENY_REASON: str = (
+    "BLOCKED [luna-fast-mode-gate]: Agent and Task Luna spawns require "
+    "service_tier fast. Native Codex Luna spawns require service_tier fast "
+    "or priority. Retry with an allowed service_tier."
+)
+
+DENY_ADDITIONAL_CONTEXT: str = (
+    "[luna-fast-mode-gate] Agent and Task Luna spawns require service_tier "
+    "fast. Native Codex Luna spawns accept service_tier fast or priority. "
+    "Retry with an allowed service_tier."
+)
+
+DENY_PREVIEW_TEMPLATE: str = "model={model_text} service_tier={service_tier_text}"
+MAXIMUM_PREVIEW_FIELD_LENGTH: int = 40

package/hooks/hooks_constants/mypy_integration_constants.py

@@ -1,16 +1,27 @@
-"""Path markers used when mypy resolves a target file's project root.
+"""Path markers and detached-file mypy CLI flags.
 
 The integration walks ancestors for a ``.git`` entry or a ``pyproject.toml``,
-and filters the check list to ``.py`` files. These names live here so the
-integration module carries no inline path or extension literals.
+and filters the check list to ``.py`` files. A file with no project root is a
+detached gate staging copy: mypy then skips followed imports and must finish
+inside a short subprocess timeout so the 30-second PreToolUse hook can return.
 """
 
 __all__ = [
     "GIT_DIRECTORY_NAME",
     "PYTHON_SOURCE_SUFFIX",
     "PYPROJECT_FILENAME",
+    "FOLLOW_IMPORTS_FLAG",
+    "FOLLOW_IMPORTS_SKIP_VALUE",
+    "MYPY_DETACHED_SUBPROCESS_TIMEOUT_SECONDS",
+    "MYPY_DETACHED_TIMEOUT_SKIP_MESSAGE",
 ]
 
 GIT_DIRECTORY_NAME: str = ".git"
 PYTHON_SOURCE_SUFFIX: str = ".py"
 PYPROJECT_FILENAME: str = "pyproject.toml"
+FOLLOW_IMPORTS_FLAG: str = "--follow-imports"
+FOLLOW_IMPORTS_SKIP_VALUE: str = "skip"
+MYPY_DETACHED_SUBPROCESS_TIMEOUT_SECONDS: int = 8
+MYPY_DETACHED_TIMEOUT_SKIP_MESSAGE: str = (
+    "mypy timed out on a detached file; skipping"
+)

package/hooks/session/AGENTS.md

@@ -1,6 +1,6 @@
 # hooks/session
 
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown. Also holds the UserPromptSubmit hook. It adds a style reminder to each message.
+SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown. Also holds the UserPromptSubmit hook. It adds a style reminder to each message.
 
 The working-style projection uses `~/.claude/rules/asd-ste100-language.md` for
 user-facing word choice, sentence style, tone, punctuation, and prose form.
@@ -13,7 +13,7 @@ user-facing word choice, sentence style, tone, punctuation, and prose form.
 | `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
 | `session_edit_tracker_cleanup.py` | SessionStart, SessionEnd | Deletes the tracker file for the running Claude Code conversation from the system temp directory — at start for a clean slate and at end for a clean exit. A tracker is read only by the conversation that wrote it, so a live idle tracker is kept while a peer cleans up |
 | `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
-| `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
+| `untracked_repo_detector.py` | — | Retired legacy script; no longer registered |
 | `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
 | `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
 | `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |

package/hooks/validators/AGENTS.md

@@ -13,6 +13,7 @@ A library of check modules used by the validation hooks. Each module focuses on
 | `run_all_validators.py` | Entry point — runs every check module and aggregates results |
 | `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
 | `pyproject_config_discovery.py` | Shared walk-up primitive that resolves a tool's pyproject.toml config from an original target path, matching the `[tool.<name>]` table the tool owns |
+| `system_temporary_roots.py` | Shared membership for OS temp roots (`gettempdir` plus `TEMP` / `TMP` / `TMPDIR` / `RUNNER_TEMP`); mypy walk stop and PreToolUse staging both call it |
 | `python_style_helpers.py` | Shared source-line splitting and function-discovery helpers imported by `python_style_checks.py` |
 
 ## Check modules
@@ -25,7 +26,7 @@ A library of check modules used by the validation hooks. Each module focuses on
 | `file_structure_checks.py` | File-level structural rules (line count, module layout) |
 | `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
 | `magic_value_checks.py` | Magic numbers and strings |
-| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects |
+| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects; stops project-root walks at the system temp directory; detached gate files skip followed imports and time out as a skip (passed) |
 | `pr_reference_checks.py` | PR references in commit messages and changelogs |
 | `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
 | `python_style_checks.py` | Python style rules (naming, imports, type hints) |

package/hooks/validators/conftest.py

@@ -6,9 +6,26 @@ from pathlib import Path
 
 VALIDATORS_DIRECTORY = Path(__file__).resolve().parent
 HOOKS_DIRECTORY = VALIDATORS_DIRECTORY.parent
+VALIDATORS_DIRECTORY_STRING = str(VALIDATORS_DIRECTORY)
+HOOKS_DIRECTORY_STRING = str(HOOKS_DIRECTORY)
 
-if str(VALIDATORS_DIRECTORY) not in sys.path:
-    sys.path.insert(0, str(VALIDATORS_DIRECTORY))
+for each_directory_string in (VALIDATORS_DIRECTORY_STRING, HOOKS_DIRECTORY_STRING):
+    if each_directory_string in sys.path:
+        sys.path.remove(each_directory_string)
+    sys.path.insert(0, each_directory_string)
 
-if str(HOOKS_DIRECTORY) not in sys.path:
-    sys.path.insert(0, str(HOOKS_DIRECTORY))
+for each_module_name in list(sys.modules):
+    if each_module_name != "hooks_constants" and not each_module_name.startswith(
+        "hooks_constants."
+    ):
+        continue
+    loaded_file = getattr(sys.modules[each_module_name], "__file__", None)
+    if loaded_file is None:
+        sys.modules.pop(each_module_name, None)
+        continue
+    try:
+        is_from_this_tree = Path(loaded_file).resolve().is_relative_to(HOOKS_DIRECTORY)
+    except (OSError, ValueError):
+        is_from_this_tree = False
+    if not is_from_this_tree:
+        sys.modules.pop(each_module_name, None)