claude-dev-env 2.13.0 → 2.14.1

package/hooks/git-hooks/pre_push.py

@@ -22,9 +22,8 @@ object name is the base when no default-branch ref resolves and when the
 pushed branch is the default branch. When every remote object name is zero
 (new branch) or stdin is empty, the gate falls back to the remote's default
 branch symbolic ref. When a default-branch ref resolves and git still reports
-no merge base, the base is unknown, so CODE_RULES enforcement is skipped with
-a printed reason rather than scoped to the stdin remote object name, which on
-a rebased tip would re-flag replayed commits.
+no merge base, the base stays pending and the hook reports the infrastructure
+status with a printed reason, preserving the scope boundary for rebased tips.
 
 Gate scope: the gate process this hook launches diffs its `--base` against the
 current checkout's HEAD, so the surface is the commits between that base and
@@ -32,14 +31,13 @@ HEAD. A push whose pushed object is HEAD reads as the branch's own work; a
 push of any other object is still scoped to HEAD.
 
 Exit codes:
-  0 - the push destination is allowed and its commits pass the gate (or
-      the gate is not installed, or CODE_RULES is skipped because a
-      default-branch ref resolved and git still reported no merge base).
+  0 - the push destination is allowed and its commits pass the gate, or the
+      gate is not installed.
   1 - the push would land a non-protected local branch onto a protected
       remote branch, or a commit introduces a blocking violation.
-  2 - unexpected invocation failure (e.g., subprocess could not launch),
-      stdin carried no parseable line, or a new-branch/empty-stdin base
-      could not be turned into a usable commit name.
+  2 - infrastructure attention is required because a subprocess could not
+      launch, stdin carried no parseable line, a base could not be resolved,
+      or a usable commit name could not be produced.
 """
 
 from __future__ import annotations
@@ -49,8 +47,9 @@ import sys
 from pathlib import Path
 from typing import NamedTuple
 
+from gate_utils import is_safe_regular_file, resolve_gate_script_path
 from git_hooks_constants import (
-    ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES,
+    ALL_FALLBACK_REMOTE_DEFAULT_BRANCH_NAMES,
     ALL_GIT_MERGE_BASE_COMMAND_PREFIX,
     ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX,
     ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX,
@@ -58,6 +57,7 @@ from git_hooks_constants import (
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
     BASE_REFERENCE_ARGUMENT,
     DEFAULT_REMOTE_BASE_REFERENCE,
+    DEFAULT_REMOTE_NAME,
     GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
     GIT_COMMAND_TIMEOUT_SECONDS,
     GIT_COMMAND_UNAVAILABLE_MESSAGE,
@@ -72,11 +72,10 @@ from git_hooks_constants import (
     MALFORMED_STDIN_LINE_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_SENTINEL,
-    ORIGIN_HEAD_SYMBOLIC_REFERENCE,
-    ORIGIN_REMOTE_TRACKING_REFERENCE_PREFIX,
     PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
     PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE,
     PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE,
+    REMOTE_BRANCH_REFERENCE_TEMPLATE,
     REMOTE_REFERENCE_FIELD_INDEX,
     STDIN_LINE_FIELD_COUNT,
     STDIN_READ_FAILURE_MESSAGE,
@@ -84,7 +83,6 @@ from git_hooks_constants import (
     UNRESOLVABLE_MERGE_BASE_MESSAGE,
     UNRESOLVABLE_MERGE_BASE_SENTINEL,
 )
-from gate_utils import is_safe_regular_file, resolve_gate_script_path
 from pre_push_base_reference import (
     resolve_remote_name_from_arguments,
     resolve_usable_base_reference,
@@ -294,24 +292,24 @@ def run_git_reference_query(all_git_arguments: tuple[str, ...]) -> str | None:
     return decoded_output.strip() or None
 
 
-def resolve_default_branch_reference() -> str | None:
+def resolve_default_branch_reference(remote_name: str = DEFAULT_REMOTE_NAME) -> str | None:
     """Return the remote-tracking ref name of the remote's default branch.
 
-    The remote's HEAD symbolic ref answers first. When it is unset, each
-    candidate default-branch remote-tracking ref answers in turn.
+    The remote's HEAD symbolic ref answers first. When it is unset, the
+    supported default-branch tracking refs answer in turn.
 
-    Resolution reads ``origin`` alone and never the remote name git passes as
-    argv[1], and its unset-``origin/HEAD`` fallback prefers ``origin/main``
-    over ``origin/master``, so a repo whose default is another branch beside a
-    legacy ``main`` resolves the wrong base ΓÇö the assumption set tracked at
-    ~/.claude/orchestrator-runs/falsify-first/parked-items.md row 3.
+    Args:
+        remote_name: Remote whose default branch provides the gate base.
 
     Returns:
         A remote-tracking ref name, or None when no default-branch ref
         resolves.
     """
+    remote_head_reference = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(
+        remote=remote_name, branch="HEAD"
+    )
     symbolic_reference = run_git_reference_query(
-        (*ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX, ORIGIN_HEAD_SYMBOLIC_REFERENCE)
+        (*ALL_GIT_SYMBOLIC_REFERENCE_COMMAND_PREFIX, remote_head_reference)
     )
     if symbolic_reference is not None:
         verified_symbolic_target = run_git_reference_query(
@@ -319,7 +317,10 @@ def resolve_default_branch_reference() -> str | None:
         )
         if verified_symbolic_target is not None:
             return symbolic_reference
-    for each_candidate_reference in ALL_DEFAULT_BRANCH_FALLBACK_REFERENCES:
+    for each_branch_name in ALL_FALLBACK_REMOTE_DEFAULT_BRANCH_NAMES:
+        each_candidate_reference = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(
+            remote=remote_name, branch=each_branch_name
+        )
         verified_reference = run_git_reference_query(
             (*ALL_GIT_VERIFY_REFERENCE_COMMAND_PREFIX, each_candidate_reference)
         )
@@ -360,7 +361,9 @@ def find_branch_update_push(stdin_text: str) -> PushLine | None:
 
 
 def resolve_default_branch_merge_base(
-    remote_branch_name: str, pushed_object_name: str
+    remote_branch_name: str,
+    pushed_object_name: str,
+    remote_name: str = DEFAULT_REMOTE_NAME,
 ) -> str | None:
     """Return the merge base of the pushed object and the default branch.
 
@@ -371,6 +374,7 @@ def resolve_default_branch_merge_base(
     Args:
         remote_branch_name: The remote branch the push updates.
         pushed_object_name: The object name the push carries.
+        remote_name: The remote whose default branch provides the gate base.
 
     Returns:
         The merge-base object name; None when no default-branch ref resolves or
@@ -378,12 +382,13 @@ def resolve_default_branch_merge_base(
         no merge base applies; or the unresolvable-merge-base sentinel when a
         default-branch ref resolves and git still reports no merge base.
     """
-    default_branch_reference = resolve_default_branch_reference()
+    default_branch_reference = resolve_default_branch_reference(remote_name)
     if default_branch_reference is None:
         return None
-    default_branch_name = default_branch_reference.removeprefix(
-        ORIGIN_REMOTE_TRACKING_REFERENCE_PREFIX
+    default_branch_prefix = REMOTE_BRANCH_REFERENCE_TEMPLATE.format(
+        remote=remote_name, branch=""
     )
+    default_branch_name = default_branch_reference.removeprefix(default_branch_prefix)
     if remote_branch_name == default_branch_name:
         return None
     # Anchors to the pushed object; deferring to the gate's HEAD-based merge-base would change behavior on non-HEAD pushes.
@@ -399,7 +404,9 @@ def resolve_default_branch_merge_base(
     return merge_base_object_name
 
 
-def resolve_gate_base_reference(stdin_text: str) -> str | None:
+def resolve_gate_base_reference(
+    stdin_text: str, remote_name: str = DEFAULT_REMOTE_NAME
+) -> str | None:
     """Return the reference the gate scopes its changed lines to.
 
     A branch update reads from the merge base with the remote default branch,
@@ -414,20 +421,24 @@ def resolve_gate_base_reference(stdin_text: str) -> str | None:
 
     Args:
         stdin_text: The pre-push stdin payload.
+        remote_name: The remote whose default branch provides the gate base.
 
     Returns:
         The gate's base reference, the no-parseable-lines sentinel, the
         unresolvable-merge-base sentinel, or None when the push only deletes
         remote branches.
     """
-    return _resolve_gate_base_from_parsed(_parse_push_stdin(stdin_text))
+    return _resolve_gate_base_from_parsed(_parse_push_stdin(stdin_text), remote_name)
 
 
-def _resolve_gate_base_from_parsed(parsed_stdin: ParsedPushStdin) -> str | None:
+def _resolve_gate_base_from_parsed(
+    parsed_stdin: ParsedPushStdin, remote_name: str = DEFAULT_REMOTE_NAME
+) -> str | None:
     """Return the gate's base reference for an already-parsed stdin payload.
 
     Args:
         parsed_stdin: The parsed stdin payload.
+        remote_name: The remote whose default branch provides the gate base.
 
     Returns:
         The merge base with the remote default branch for a branch update, the
@@ -440,7 +451,9 @@ def _resolve_gate_base_from_parsed(parsed_stdin: ParsedPushStdin) -> str | None:
     if branch_update is None:
         return _resolve_base_reference_from_lines(parsed_stdin)
     merge_base_object_name = resolve_default_branch_merge_base(
-        branch_update.remote_branch_name, branch_update.local_object_name
+        branch_update.remote_branch_name,
+        branch_update.local_object_name,
+        remote_name,
     )
     if merge_base_object_name is None:
         return branch_update.remote_object_name
@@ -542,7 +555,8 @@ def main() -> int:
             file=sys.stderr,
         )
         return 0
-    base_reference = _resolve_gate_base_from_parsed(parsed_stdin)
+    remote_name = resolve_remote_name_from_arguments(sys.argv)
+    base_reference = _resolve_gate_base_from_parsed(parsed_stdin, remote_name)
     if base_reference is None:
         return 0
     if base_reference == no_parseable_stdin_lines_sentinel:
@@ -550,8 +564,7 @@ def main() -> int:
         return gate_infrastructure_failure_exit_code
     if base_reference == unresolvable_merge_base_sentinel:
         print(unresolvable_merge_base_message, file=sys.stderr)
-        return 0
-    remote_name = resolve_remote_name_from_arguments(sys.argv)
+        return gate_infrastructure_failure_exit_code
     try:
         usable_base_reference = resolve_usable_base_reference(
             base_reference, remote_name, run_git_text_command

package/hooks/git-hooks/test_pre_push.py

@@ -156,11 +156,10 @@ def test_run_git_reference_query_returns_replaced_text_on_locale_invalid_bytes(
     assert resolved_output == expected_replaced_reference
 
 
-def test_unresolvable_merge_base_message_does_not_claim_dangling_origin_head() -> None:
+def test_unresolvable_merge_base_message_describes_pending_validation() -> None:
     skip_message = git_hooks_constants.UNRESOLVABLE_MERGE_BASE_MESSAGE
-    assert "origin/HEAD names a ref" not in skip_message
-    assert "unrelated histories" in skip_message
-    assert "merge-base still could not name a shared commit" in skip_message
+    assert "CODE_RULES validation is pending" in skip_message
+    assert "Restore shared history" in skip_message
 
 
 def test_run_git_text_command_raises_when_git_cannot_launch(
@@ -239,6 +238,11 @@ def resolve_remote_head_reference(monkeypatch: pytest.MonkeyPatch) -> None:
         return GIT_RESOLVED_EXIT_CODE, RESOLVED_COMMIT_OBJECT_NAME
 
     monkeypatch.setattr(pre_push, "run_git_text_command", fake_run_git_text_command)
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [HOOK_INVOCATION_NAME, git_hooks_constants.DEFAULT_REMOTE_NAME, PUSHED_REMOTE_URL],
+    )
 
 
 
@@ -994,6 +998,46 @@ def test_resolve_default_branch_reference_reads_the_origin_head_symbolic_referen
     assert pre_push.resolve_default_branch_reference() == ORIGIN_DEFAULT_BRANCH_REFERENCE
 
 
+def test_resolve_default_branch_reference_reads_the_requested_remote_head(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, _topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    upstream_reference = "refs/remotes/upstream/main"
+    upstream_head_reference = "refs/remotes/upstream/HEAD"
+    _run_fixture_git(repository, "update-ref", upstream_reference, default_branch_tip)
+    _run_fixture_git(
+        repository, "symbolic-ref", upstream_head_reference, upstream_reference
+    )
+    monkeypatch.chdir(repository)
+
+    assert pre_push.resolve_default_branch_reference("upstream") == upstream_reference
+
+
+def test_resolve_default_branch_merge_base_uses_requested_remote_trunk_fallback(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    upstream_trunk_reference = "refs/remotes/upstream/trunk"
+    _run_fixture_git(
+        repository, "update-ref", upstream_trunk_reference, default_branch_tip
+    )
+    monkeypatch.chdir(repository)
+
+    merge_base_object_name = pre_push.resolve_default_branch_merge_base(
+        FEATURE_BRANCH_NAME,
+        topic_branch_tip,
+        "upstream",
+    )
+
+    assert merge_base_object_name == default_branch_tip
+
+
 def test_resolve_default_branch_reference_returns_none_without_remote_tracking_refs(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
@@ -1198,7 +1242,7 @@ def test_main_allows_the_push_when_origin_head_names_an_absent_reference(
     assert recorded_arguments == ["--base", remote_object_name]
 
 
-def test_main_skips_the_gate_when_no_merge_base_resolves(
+def test_main_keeps_the_gate_pending_when_no_merge_base_resolves(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],
@@ -1230,13 +1274,73 @@ def test_main_skips_the_gate_when_no_merge_base_resolves(
 
     exit_code = pre_push.main()
 
-    assert exit_code == 0
+    assert exit_code == git_hooks_constants.GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE
     assert not recorded_arguments_path.exists(), (
-        "the gate ran on a base the hook could not verify"
+        "the gate remains pending until the hook verifies a usable base"
     )
     assert git_hooks_constants.UNRESOLVABLE_MERGE_BASE_MESSAGE in capsys.readouterr().err
 
 
+def test_main_uses_the_pushed_remote_when_origin_has_unrelated_history(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    repository, default_branch_tip, topic_branch_tip = _build_default_branch_repository(
+        tmp_path
+    )
+    _run_fixture_git(repository, "checkout", "--orphan", "unrelated-origin")
+    _run_fixture_git(repository, "rm", "-rf", ".")
+    unrelated_origin_tip = _commit_file(repository, "unrelated.txt")
+    _run_fixture_git(repository, "checkout", FEATURE_BRANCH_NAME)
+    _run_fixture_git(
+        repository,
+        "update-ref",
+        ORIGIN_DEFAULT_BRANCH_REFERENCE,
+        unrelated_origin_tip,
+    )
+    _set_origin_head(repository, ORIGIN_DEFAULT_BRANCH_REFERENCE)
+    upstream_reference = "refs/remotes/upstream/main"
+    upstream_head_reference = "refs/remotes/upstream/HEAD"
+    _run_fixture_git(repository, "update-ref", upstream_reference, default_branch_tip)
+    _run_fixture_git(
+        repository, "symbolic-ref", upstream_head_reference, upstream_reference
+    )
+    recorded_arguments_path = tmp_path / "upstream_recorded_arguments.txt"
+    recording_gate_script_path = tmp_path / "upstream_recording_gate.py"
+    recording_gate_script_path.write_text(
+        "import pathlib, sys\n"
+        f'pathlib.Path(r"{recorded_arguments_path}").write_text('
+        "'\\n'.join(sys.argv[1:]), encoding='utf-8')\n"
+        "sys.exit(0)\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(recording_gate_script_path))
+    monkeypatch.chdir(repository)
+    monkeypatch.setattr(
+        sys, "argv", [HOOK_INVOCATION_NAME, PUSHED_REMOTE_NAME, PUSHED_REMOTE_URL]
+    )
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            _push_stdin_line(
+                FEATURE_BRANCH_NAME,
+                topic_branch_tip,
+                FEATURE_BRANCH_NAME,
+                NON_ZERO_REMOTE_SHA_ONE,
+            )
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0
+    assert recorded_arguments_path.read_text(encoding="utf-8").splitlines() == [
+        "--base",
+        default_branch_tip,
+    ]
+
+
 def test_main_allows_default_branch_file_the_rebase_replayed_onto(
     tmp_path: Path,
     monkeypatch: pytest.MonkeyPatch,

package/hooks/hooks_constants/AGENTS.md

@@ -0,0 +1,104 @@
+# hooks/hooks_constants
+
+Shared constant modules imported by hooks throughout the `hooks/` tree. Each file holds the tunables for one hook or one cross-cutting concern, keeping magic values out of the hook scripts themselves.
+
+## Files
+
+| File | What it holds |
+|---|---|
+| `__init__.py` | Package marker (`# pragma: no-tdd-gate`) |
+| `any_type_config.py` | Config for the `Any`-type escape-hatch check |
+| `ask_user_question_shape.py` | Pure AskUserQuestion lean-block shape analyzer: grades question and option-description prose against shared chat-detail markers and sentence/word caps with no hook I/O |
+| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
+| `bash_pre_tool_use_dispatcher_constants.py` | Permission outcomes, tool-name sets, and the ordered hosted-hook roster for the Bash PreToolUse dispatcher (also covers PowerShell-shared gates) |
+| `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
+| `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
+| `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
+| `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
+| `enter_worktree_prefetch_constants.py` | Tool name, origin-remote ref names, and git-command timeouts for the EnterWorktree origin-prefetch hook |
+| `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
+| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
+| `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
+| `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
+| `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
+| `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
+| `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
+| `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
+| `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
+| `docstring_rule_gate_count_blocker_constants.py` | Target rule basename, spelled-out-number lookup, count-clause and `check_*` validator patterns, and block-message text for the docstring-rule gate-count staleness blocker |
+| `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
+| `duplicate_rmtree_helper_blocker_constants.py` | Sanctioned Windows-safe rmtree helper names, the definition pattern, and the exempt-path set for the duplicate-rmtree-helper blocker |
+| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
+| `eli11_reply_enforcer_constants.py` | Reply-shape thresholds (bullet cap, lead-line window, per-list-line word cap, overpacked list-line cap), the bullet / numbered-step / table-row / link-target / word patterns, the imperative instruction verbs, and the user-facing notice for the ELI11 reply-shape Stop hook |
+| `fable_spawn_gate_constants.py` | The spawn tool-name set, the fable model alias and the model-id segment split pattern, the `FABLE-SPAWN-AUTHORIZED` authorization token, the advisor-protocol document path, payload field names, the deny message, and the deny `additionalContext` recovery text for the fable-tier spawn gate |
+| `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
+| `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
+| `harness_scratchpad_constants.py` | Fixed path components (`claude` / `claude-` user-directory name and prefix, `scratchpad` leaf name), the PreToolUse session-id payload key, and the `CLAUDE_CODE_SESSION_ID` environment variable name that the code-rules and TDD gates use to recognize an existing harness session scratchpad directory |
+| `hedging_uncertainty_constants.py` | Sentence-boundary pattern, explicit uncertainty label patterns, hedge-term list separator, and positive corrective block text for OP-07C sentence-scoped hedging |
+| `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
+| `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
+| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
+| `hosted_hook_runner.py` | `run_hook_capturing_output()` — shared runner that runs one dispatcher-hosted hook in-process via runpy and returns its captured stdout and crash flag |
+| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
+| `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
+| `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_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 |
+| `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
+| `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
+| `paired_test_coverage_constants.py` | Test-directory name, stem-test filename affixes, test-file globs, exempt public-function names, scan budget, coverage threshold, and guidance text for the public-function paired-test coverage check |
+| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
+| `pii_prevention_constants.py` | Patterns, allowlists, path exemptions, and deny-message text for `pii_prevention_blocker` |
+| `piped_pytest_blocker_constants.py` | Bash tool name, pytest program basenames and the python-interpreter basename pattern, the pipe and segment-reset operator token sets, and the deny message for the piped-pytest blocker; classification that consumes those program and wrapper constants lives in `pytest_invocation.py` |
+| `pytest_invocation.py` | Pure parsed-segment classifier for pytest runs through interpreters, shims, wrappers, and shell string-exec forms; no pipeline deny decision |
+| `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
+| `prose_matcher_precision_constants.py` | Sample floor, keep/narrow precision floors, matcher ids, label decisions, advisory log path, emit caps, and context fingerprint length for OP-07B prose-matcher advisory telemetry |
+| `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
+| `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
+| project_paths_reader.py | Loads ~/.claude/project-paths.json and finds a home-bounded git root for registry checks |
+| `pyproject_config_discovery_constants.py` | Table names (``tool`` key, ``mypy``, ``ruff``) for resolving a validator's config from a pyproject.toml `[tool.<name>]` table |
+| `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
+| `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
+| `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
+| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
+| `sensitive_file_protector_constants.py` | Sensitive filename patterns, the committed-template suffixes that earn an exemption, the write/edit tool names, and the deny decision and message template for `sensitive_file_protector` |
+| `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
+| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
+| `session_start_injector.py` | Pure SessionStart context injector: normalize `source` (`startup`/`resume`/`clear`/`compact`), honor enable/timeout, return structured injection results for starter hooks |
+| `session_start_injector_constants.py` | Known SessionStart source values, injection status codes, enable env var, default timeout for the shared injector |
+| `test_session_start_injector.py` | Behavioral tests for every known source, disabled, timeout, and unknown-source paths |
+| `orchestrator_auto_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the orchestrator auto-starter |
+| `issue_tracker_session_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the repository-gated issue-tracker starter |
+| `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
+| `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
+| `shell_command_pipeline.py` | Quote-aware shell pipeline parsing: operator-paired segments after line-continuation join, comment strip, heredoc body drop, and parenthesis-group join |
+| `shell_command_segments.py` | Shell tokenization helpers shared by the segment-walking blockers: segment splitting on control operators, a segment's effective leading program, and a token's basename |
+| `shell_substitution_blocker_constants.py` | Tool name, payload keys, the four substitution-detection patterns, the deny decision shape, and the corrective message for the shell-substitution blocker |
+| `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
+| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
+| `stop_dispatcher_constants.py` | Ordered hosted-hook roster and Stop block payload field names for the Stop-chain dispatcher |
+| `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
+| `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
+| `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
+| `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
+| `task_list_loop_starter_constants.py` | The one-line task-list instruction and the full session-start directive text for the task-list loop starter hook |
+| `test_layout_constants.py` | The named constants for the test-layout write-time checks |
+| `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
+| `unscoped_search_blocker_constants.py` | Tool names, `find` and listing program basenames, Get-ChildItem option sets, unscoped-root patterns, the flag/value token stride, and the deny message for the unscoped-search blocker |
+| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
+| `volatile_path_in_post_blocker_constants.py` | Volatile path markers, affected `gh` post subcommands, MCP body param names, and the corrective message for the volatile-path post blocker |
+| `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
+| `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
+| `working_style_prompt_constants.py` | The fixed multi-paragraph working-style prompt text for the SessionStart working_style_prompt hook |
+
+## Conventions
+
+- Most files in this package are pure constants modules — no side effects, no I/O.
+- Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
+- Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
+- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they hold logic shared across hook surfaces.
+- `local_identity.py` is a loader: it reads the environment or `~/.claude/local-identity.json` (its path overridable via `CLAUDE_LOCAL_IDENTITY_PATH`) to resolve private NAS values (with committed 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`).

package/hooks/hooks_constants/CLAUDE.md

@@ -1,104 +1 @@
-# hooks/hooks_constants
-
-Shared constant modules imported by hooks throughout the `hooks/` tree. Each file holds the tunables for one hook or one cross-cutting concern, keeping magic values out of the hook scripts themselves.
-
-## Files
-
-| File | What it holds |
-|---|---|
-| `__init__.py` | Package marker (`# pragma: no-tdd-gate`) |
-| `any_type_config.py` | Config for the `Any`-type escape-hatch check |
-| `ask_user_question_shape.py` | Pure AskUserQuestion lean-block shape analyzer: grades question and option-description prose against shared chat-detail markers and sentence/word caps with no hook I/O |
-| `banned_identifiers_constants.py` | The set of banned short identifiers and banned function-name prefixes |
-| `bash_pre_tool_use_dispatcher_constants.py` | Permission outcomes, tool-name sets, and the ordered hosted-hook roster for the Bash PreToolUse dispatcher (also covers PowerShell-shared gates) |
-| `blocking_check_limits.py` | Max issue counts and preview lengths for blocking hooks |
-| `bot_mention_comment_blocker_constants.py` | Patterns for detecting bot @-mentions in PR comments |
-| `claude_md_orphan_file_blocker_constants.py` | Table patterns, file extensions, scan budget, and block-message text for the CLAUDE.md orphan-file blocker |
-| `code_rules_enforcer_constants.py` | File-extension sets, test-path patterns, advisory line thresholds, boolean-name prefixes |
-| `enter_worktree_prefetch_constants.py` | Tool name, origin-remote ref names, and git-command timeouts for the EnterWorktree origin-prefetch hook |
-| `env_var_table_code_drift_constants.py` | Table patterns, env-var-name and code-file recognizers, scan budget, and block-message text for the env-var-table code-drift blocker |
-| `code_rules_path_utils_constants.py` | Path-matching helpers used by the code-rules check modules |
-| `command_dispatch_constants.py` | Command-word regex, command-key access pattern, tokenization pattern, and anchors for the unanchored command-dispatch meta-gate |
-| `conventional_pr_title_gate_constants.py` | Bash tool name, gh executable basenames and pr create/edit subcommand tokens, title/repo flag names, semantic-title-CI workflow markers, the Conventional Commits type list and title pattern, the semantic-pull-request action `types:` input pattern, and block-message text for the conventional-PR-title gate |
-| `dead_argparse_argument_constants.py` | Patterns for detecting unused argparse arguments |
-| `dead_config_field_constants.py` | Patterns for detecting unused `*Config` / `*Selectors` dataclass fields |
-| `dead_dataclass_field_constants.py` | Patterns for detecting unused dataclass fields |
-| `dead_module_constant_constants.py` | Patterns for detecting unexported `UPPER_SNAKE` constants in `*_constants.py` modules |
-| `destructive_command_segment_constants.py` | The list of destructive shell command patterns the blocker matches |
-| `docstring_rule_gate_count_blocker_constants.py` | Target rule basename, spelled-out-number lookup, count-clause and `check_*` validator patterns, and block-message text for the docstring-rule gate-count staleness blocker |
-| `duplicate_function_body_constants.py` | Hashing and comparison config for the duplicate-body check |
-| `duplicate_rmtree_helper_blocker_constants.py` | Sanctioned Windows-safe rmtree helper names, the definition pattern, and the exempt-path set for the duplicate-rmtree-helper blocker |
-| `dynamic_stderr_handler.py` | `DynamicStderrHandler` — a logging handler that resolves `sys.stderr` at emit time (for testability) |
-| `eli11_reply_enforcer_constants.py` | Reply-shape thresholds (bullet cap, lead-line window, per-list-line word cap, overpacked list-line cap), the bullet / numbered-step / table-row / link-target / word patterns, the imperative instruction verbs, and the user-facing notice for the ELI11 reply-shape Stop hook |
-| `fable_spawn_gate_constants.py` | The spawn tool-name set, the fable model alias and the model-id segment split pattern, the `FABLE-SPAWN-AUTHORIZED` authorization token, the advisor-protocol document path, payload field names, the deny message, and the deny `additionalContext` recovery text for the fable-tier spawn gate |
-| `gh_pr_author_swap_constants.py` | Constants for the PR-author swap enforcement hooks |
-| `hardcoded_user_path_constants.py` | Patterns for detecting hardcoded home-directory paths |
-| `harness_scratchpad_constants.py` | Fixed path components (`claude` / `claude-` user-directory name and prefix, `scratchpad` leaf name), the PreToolUse session-id payload key, and the `CLAUDE_CODE_SESSION_ID` environment variable name that the code-rules and TDD gates use to recognize an existing harness session scratchpad directory |
-| `hedging_uncertainty_constants.py` | Sentence-boundary pattern, explicit uncertainty label patterns, hedge-term list separator, and positive corrective block text for OP-07C sentence-scoped hedging |
-| `hook_block_logger.py` | `log_hook_block()` — shared fail-safe logger every blocking hook calls to append a JSON record of each block decision to `~/.claude/logs/hook-blocks.log` |
-| `hook_log_extractor_constants.py` | Neon table name, offset state file path, timeouts, and outcome-type mapping for the hook-log extractor |
-| `hook_prose_detector_consistency_constants.py` | Trigger patterns and corrective messages for the hook-prose consistency checker |
-| `hosted_hook_runner.py` | `run_hook_capturing_output()` — shared runner that runs one dispatcher-hosted hook in-process via runpy and returns its captured stdout and crash flag |
-| `inline_tuple_string_magic_constants.py` | Patterns for detecting magic strings in inline tuple literals |
-| `js_conventions_constants.py` | Banned identifier set, boolean-prefix pattern, and declaration/JSDoc patterns for the JavaScript convention checks |
-| `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_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 |
-| `orphan_css_class_constants.py` | Scan radius and selector patterns for the orphan-CSS-class check |
-| `package_inventory_stale_blocker_constants.py` | Inventory document names, production code extensions, backtick token pattern, smallest inventory size, exempt names, scan budget, and block-message text for the package-inventory stale-entry blocker |
-| `paired_test_coverage_constants.py` | Test-directory name, stem-test filename affixes, test-file globs, exempt public-function names, scan budget, coverage threshold, and guidance text for the public-function paired-test coverage check |
-| `path_rewriter_constants.py` | Path rewriting patterns for the Everything-search path rewriter |
-| `pii_prevention_constants.py` | Patterns, allowlists, path exemptions, and deny-message text for `pii_prevention_blocker` |
-| `piped_pytest_blocker_constants.py` | Bash tool name, pytest program basenames and the python-interpreter basename pattern, the pipe and segment-reset operator token sets, and the deny message for the piped-pytest blocker; classification that consumes those program and wrapper constants lives in `pytest_invocation.py` |
-| `pytest_invocation.py` | Pure parsed-segment classifier for pytest runs through interpreters, shims, wrappers, and shell string-exec forms; no pipeline deny decision |
-| `plain_language_blocker_constants.py` | The list of heavy words and their everyday replacements |
-| `prose_matcher_precision_constants.py` | Sample floor, keep/narrow precision floors, matcher ids, label decisions, advisory log path, emit caps, and context fingerprint length for OP-07B prose-matcher advisory telemetry |
-| `pre_tool_use_stdin.py` | `read_hook_input_dictionary_from_stdin()` — shared stdin parser for PreToolUse hooks |
-| `precommit_code_rules_gate_constants.py` | Scope argument and exit-code constants for the precommit gate |
-| project_paths_reader.py | Loads ~/.claude/project-paths.json and finds a home-bounded git root for registry checks |
-| `pyproject_config_discovery_constants.py` | Table names (``tool`` key, ``mypy``, ``ruff``) for resolving a validator's config from a pyproject.toml `[tool.<name>]` table |
-| `pytest_testpaths_orphan_blocker_constants.py` | Marker filename, section and key names, test-file pattern, search budget, and block-message text for the pytest unregistered-test-directory blocker |
-| `python_style_checks_constants.py` | Command-line argument count and blank-line count between top-level functions for the style validator |
-| `ruff_integration_constants.py` | ``NO_COLOR`` / ``FORCE_COLOR`` environment variable names for plain ruff diagnostics |
-| `send_user_file_open_locally_blocker_constants.py` | Tool name, proactive status, and the block message for the open-locally attach blocker |
-| `sensitive_file_protector_constants.py` | Sensitive filename patterns, the committed-template suffixes that earn an exemption, the write/edit tool names, and the deny decision and message template for `sensitive_file_protector` |
-| `session_edit_stage_gate_constants.py` | Tracker filename prefix/suffix, JSON payload key, edit tool name set, session-id sanitize pattern, lock filename suffix and lock-acquire timing, git diff command, commit flag escapes, and deny-message template shared by the session edit stage gate trio |
-| `session_env_cleanup_constants.py` | Stale-age threshold and directory names for the session-env cleanup hook |
-| `session_start_injector.py` | Pure SessionStart context injector: normalize `source` (`startup`/`resume`/`clear`/`compact`), honor enable/timeout, return structured injection results for starter hooks |
-| `session_start_injector_constants.py` | Known SessionStart source values, injection status codes, enable env var, default timeout for the shared injector |
-| `test_session_start_injector.py` | Behavioral tests for every known source, disabled, timeout, and unknown-source paths |
-| `orchestrator_auto_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the orchestrator auto-starter |
-| `issue_tracker_session_starter_constants.py` | Opt-in env var, enable values, timeout, and SessionStart directive text for the repository-gated issue-tracker starter |
-| `session_handoff_blocker_constants.py` | Trigger phrases for the session-handoff blocker |
-| `setup_project_paths_constants.py` | Encoding policy, BOM marker, and registry meta-key used across multiple hooks |
-| `shell_command_pipeline.py` | Quote-aware shell pipeline parsing: operator-paired segments after line-continuation join, comment strip, heredoc body drop, and parenthesis-group join |
-| `shell_command_segments.py` | Shell tokenization helpers shared by the segment-walking blockers: segment splitting on control operators, a segment's effective leading program, and a token's basename |
-| `shell_substitution_blocker_constants.py` | Tool name, payload keys, the four substitution-detection patterns, the deny decision shape, and the corrective message for the shell-substitution blocker |
-| `stale_comment_reference_blocker_constants.py` | Identifier pattern, comment stopwords, and denial text for the stale-comment-reference blocker |
-| `state_description_blocker_constants.py` | The set of historical/comparative phrases the state-description blocker rejects, plus the docstring-extraction and mention-span patterns for its Python docstring scan |
-| `stop_dispatcher_constants.py` | Ordered hosted-hook roster and Stop block payload field names for the Stop-chain dispatcher |
-| `stuttering_check_config.py` | Config for the stuttering (repeated-phrase) check |
-| `stuttering_import_binding_constants.py` | Import-binding patterns for the stuttering check |
-| `subprocess_budget_completeness_constants.py` | Required argument names for the subprocess-budget completeness check |
-| `sys_path_insert_constants.py` | Patterns for detecting unguarded `sys.path.insert` calls |
-| `task_list_loop_starter_constants.py` | The one-line task-list instruction and the full session-start directive text for the task-list loop starter hook |
-| `test_layout_constants.py` | The named constants for the test-layout write-time checks |
-| `text_stripping.py` | `strip_code_and_quotes()` — shared helper that removes fenced code blocks, inline code, and blockquotes from prose, imported by the Stop-hook prose blockers |
-| `unscoped_search_blocker_constants.py` | Tool names, `find` and listing program basenames, Get-ChildItem option sets, unscoped-root patterns, the flag/value token stride, and the deny message for the unscoped-search blocker |
-| `unused_module_import_constants.py` | Patterns for detecting unused module-level imports |
-| `volatile_path_in_post_blocker_constants.py` | Volatile path markers, affected `gh` post subcommands, MCP body param names, and the corrective message for the volatile-path post blocker |
-| `windows_rmtree_blocker_constants.py` | The unsafe `shutil.rmtree` pattern and the safe replacement pattern |
-| `workflow_substitution_slot_blocker_constants.py` | Per-iteration token patterns for the workflow-slot blocker |
-| `working_style_prompt_constants.py` | The fixed multi-paragraph working-style prompt text for the SessionStart working_style_prompt hook |
-
-## Conventions
-
-- Most files in this package are pure constants modules — no side effects, no I/O.
-- Hooks import from this package with `from hooks_constants.<module> import <CONSTANT>`.
-- Tests for these modules live beside them as `test_<module>.py`. Run with `python -m pytest hooks_constants/test_<name>.py`.
-- `dynamic_stderr_handler.py`, `pre_tool_use_stdin.py`, `multi_edit_reconstruction.py`, `hosted_hook_runner.py`, and `text_stripping.py` are utility modules (not pure constants) but live here because they hold logic shared across hook surfaces.
-- `local_identity.py` is a loader: it reads the environment or `~/.claude/local-identity.json` (its path overridable via `CLAUDE_LOCAL_IDENTITY_PATH`) to resolve private NAS values (with committed 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`).
+@AGENTS.md

package/hooks/hooks_constants/hook_log_extractor_constants.py

@@ -123,7 +123,7 @@ SUMMARY_COLUMN_HEADINGS: tuple[str, str, str, str] = (
     "top_blocked_command_preview",
 )
 
-SUMMARY_NO_NEW_BLOCKS_MESSAGE: str = "No new blocks since last run."
+SUMMARY_ZERO_BLOCKED_EVENTS_MESSAGE: str = "Blocked events recorded in the last 24 hours: 0."
 
 QUERY_NO_ROWS_RETURNED_MESSAGE: str = "No rows returned."
 
@@ -231,4 +231,3 @@ WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG: int = 0x00000200
 
 LOCK_MAXIMUM_RETRY_COUNT: int = 30
 LOCK_RETRY_SLEEP_SECONDS: float = 0.1
-

package/hooks/hooks_constants/task_list_loop_starter_constants.py

@@ -11,8 +11,9 @@ TASK_LIST_MAINTENANCE_INSTRUCTION = "build or update the task list using the tas
 
 TASK_LIST_LOOP_DIRECTIVE = (
     "TASK LIST MAINTENANCE: Keep this session's task list current on a 10-minute "
-    "cadence. If a task-list maintenance loop is not already running this session, "
-    "start one now with Claude Code's built-in /loop skill on a 10-minute interval: "
+    "cadence. Reuse the active task-list maintenance loop when available. Start "
+    "Claude Code's built-in /loop skill with a 10-minute interval when this session "
+    "needs its first loop: "
     f'/loop 10m "{TASK_LIST_MAINTENANCE_INSTRUCTION}". Run that instruction once '
-    "immediately, then let the loop refresh the list every 10 minutes."
+    "immediately when starting the loop, then let the loop refresh the list every 10 minutes."
 )