claude-dev-env 2.25.0 → 2.27.0

package/bin/install.test.mjs

@@ -24,6 +24,7 @@ import {
     INSTALL_GROUPS,
     FOLDED_HOOK_RELATIVE_PATHS,
     POST_FOLDED_HOOK_RELATIVE_PATHS,
+    RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS,
     pythonCandidatesForPlatform,
     isWindowsStorePythonStub,
     interpreterCommandFromPath,
@@ -718,6 +719,26 @@ test('mergeHooksIntoSettings matches full standalone arguments at boundaries', (
 });
 
 
+test('mergeHooksIntoSettings substitutes an absolute interpreter path for the python prefix', () => {
+    const hooksConfig = {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: 'Agent',
+                    hooks: [{ type: 'command', command: 'python ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/luna_fast_mode_gate.py' }],
+                },
+            ],
+        },
+    };
+    const settings = {};
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/x/.claude', 'C:/Python313/python.exe');
+    assert.equal(
+        settings.hooks.PreToolUse[0].hooks[0].command,
+        'C:/Python313/python.exe C:/Users/x/.claude/hooks/blocking/luna_fast_mode_gate.py',
+    );
+});
+
+
 test('mergeHooksIntoSettings prunes a prior py -3 managed hook when reinstalling with an absolute interpreter path', () => {
     const hooksConfig = {
         hooks: {
@@ -1193,12 +1214,27 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('FOLDED_HOOK_RELATIVE_PATHS contains all 14 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 15);
+test('FOLDED_HOOK_RELATIVE_PATHS contains folded hooks plus retired entries', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/md_to_html_blocker.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('session/untracked_repo_detector.py'));
+});
+
+
+test('retired hook registrations stay managed so reinstall removes them', () => {
+    const retiredPath = 'session/untracked_repo_detector.py';
+    const shippedHooks = JSON.parse(
+        readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8')
+    );
+    const shippedCommands = Object.values(shippedHooks.hooks).flatMap(matcherGroups => (
+        matcherGroups.flatMap(matcherGroup => matcherGroup.hooks.map(hook => hook.command))
+    ));
+    assert.deepEqual(RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS, new Set([retiredPath]));
+    assert.ok(managedHookScriptRelativePaths({ hooks: {} }).has(retiredPath));
+    assert.ok(shippedCommands.every(command => !command.includes(retiredPath)));
 });
 
 
@@ -1221,6 +1257,7 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
     ];
     const retiredHooks = [
         'blocking/md_to_html_blocker.py',
+        'session/untracked_repo_detector.py',
     ];
     for (const hostedPath of dispatcherHostedHooks) {
         assert.ok(
@@ -1242,6 +1279,41 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
 });
 
 
+test('mergeHooksIntoSettings removes the retired SessionStart detector and keeps user hooks', () => {
+    const retiredCommand = 'py -3 C:/Users/x/.claude/hooks/session/untracked_repo_detector.py';
+    const userCommand = 'py -3 C:/Users/x/custom/session_gate.py';
+    const settings = {
+        hooks: {
+            SessionStart: [{
+                matcher: '',
+                hooks: [
+                    { type: 'command', command: retiredCommand },
+                    { type: 'command', command: userCommand },
+                ],
+            }],
+        },
+    };
+    const currentHooksConfig = {
+        hooks: {
+            SessionStart: [{
+                matcher: '',
+                hooks: [{
+                    type: 'command',
+                    command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/plugin_data_dir_cleanup.py',
+                }],
+            }],
+        },
+    };
+
+    mergeHooksIntoSettings(settings, currentHooksConfig, 'C:/Users/x/.claude', 'py -3');
+
+    const commands = settings.hooks.SessionStart[0].hooks.map(hook => hook.command);
+    assert.equal(commands.includes(retiredCommand), false);
+    assert.equal(commands.includes(userCommand), true);
+    assert.equal(commands.some(command => command.includes('plugin_data_dir_cleanup.py')), true);
+});
+
+
 test('managedHookScriptRelativePaths includes the dispatcher and all folded hooks so old entries are prunable', () => {
     const relativePaths = managedHookScriptRelativePaths(DISPATCHER_HOOKS_CONFIG);
     assert.ok(relativePaths.has('blocking/pre_tool_use_dispatcher.py'), 'dispatcher must be in managed set');
@@ -1319,6 +1391,14 @@ test('shipped hooks.json matches the dispatcher design: dispatchers registered,
         .filter(cmd => cmd.includes('post_tool_use_dispatcher.py'));
     assert.equal(postDispatcherCommands.length, 1, 'shipped hooks.json must register the PostToolUse dispatcher exactly once');
 
+    const allSessionStartCommands = (shippedHooksConfig.hooks.SessionStart || [])
+        .flatMap(group => group.hooks.map(hook => hook.command));
+    assert.equal(
+        allSessionStartCommands.some(command => command.includes('untracked_repo_detector.py')),
+        false,
+        'shipped hooks.json must not register the retired untracked-repo detector',
+    );
+
     const writePathCommands = allPreToolUseGroups
         .filter(group => /Write|Edit|MultiEdit/.test(group.matcher || ''))
         .flatMap(group => group.hooks.map(hook => hook.command));

package/commands/sr-loop.md

@@ -10,6 +10,14 @@ tool and repeats it until a pass returns zero new findings.
 Use `rules/asd-ste100-language.md` for user-facing wording. Keep the loop's
 cleanup, verification, commit, push, and finish-report fields.
 
+### Nit-only terminal
+
+When a pass finds only nits, apply them, run scoped checks, commit, and push.
+Treat that phase as clean. Do not run another simplify or review pass without
+the user's request. If later work creates an uncommitted out-of-scope diff,
+stop and report it. Do not inspect, repair, commit, or adopt that diff without
+new user instruction.
+
 ## Effort
 
 Set every model call to `max` effort. If that model has no `max` effort, use
@@ -32,7 +40,8 @@ stack's design, intent, and changes.
    written with the Write tool, Co-Authored-By line, 10-minute timeout — the
    pre-commit gate runs its own tests), and push to the PR head branch. The PR
    stays draft.
-3. Repeat the invocation. **Skips are sticky:** carry every adjudicated skip
+3. Repeat the invocation only after substantive findings or a user request.
+   **Skips are sticky:** carry every adjudicated skip
    forward into the next pass as "already adjudicated — do not re-report: ..."
    context, or the loop never converges.
 4. Phase A converges when a full pass returns zero new findings, or when a

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