claude-dev-env 2.29.0 → 2.30.1

package/hooks/blocking/test_code_rules_validation_phase.py

@@ -0,0 +1,332 @@
+"""Tests for the validate_content edit-lane and full-gate phase split."""
+
+from __future__ import annotations
+
+import ast
+import contextlib
+import importlib
+import importlib.util
+import inspect
+import re
+import shutil
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+from types import ModuleType
+from unittest.mock import DEFAULT, MagicMock, patch
+
+import pytest
+
+
+def _load_module_from_path(module_name: str, module_path: Path) -> ModuleType:
+    """Load and execute the module found at module_path, under module_name."""
+    specification = importlib.util.spec_from_file_location(module_name, module_path)
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+    return module
+
+
+_BLOCKING_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_DIRECTORY = _BLOCKING_DIRECTORY.parent
+_PACKAGE_ROOT = _HOOKS_DIRECTORY.parent
+_PR_LOOP_SCRIPTS_DIRECTORY = str(_PACKAGE_ROOT / "_shared" / "pr-loop" / "scripts")
+
+code_rules_enforcer = _load_module_from_path(
+    "code_rules_enforcer", _BLOCKING_DIRECTORY / "code_rules_enforcer.py"
+)
+validation_phase_constants = _load_module_from_path(
+    "validation_phase_constants",
+    _HOOKS_DIRECTORY / "hooks_constants" / "validation_phase_constants.py",
+)
+
+if _PR_LOOP_SCRIPTS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _PR_LOOP_SCRIPTS_DIRECTORY)
+enforcer_loading = importlib.import_module("code_rules_gate_parts.enforcer_loading")
+gate_running = importlib.import_module("code_rules_gate_parts.gate_running")
+repo_test_helpers = importlib.import_module("code_rules_gate_parts.tests._repo_test_helpers")
+
+PRODUCTION_FILE_PATH = "packages/app/services.py"
+SAMPLE_PYTHON_CONTENT = "def add_one(value: int) -> int:\n    return value + 1\n"
+UNKNOWN_PHASE_NAME = "not_a_real_phase"
+HOOK_INFRASTRUCTURE_FILE_PATH = "/repo/packages/claude-dev-env/hooks/blocking/example.py"
+_HOOK_MODULE_DUPLICATE_BODY_SOURCE = (
+    "def compute_shipping_total(order_total: float, tax_rate: float) -> float:\n"
+    "    taxed_total = order_total * (1 + tax_rate)\n"
+    "    rounded_total = round(taxed_total, 2)\n"
+    "    return rounded_total\n"
+)
+
+
+def test_all_validation_phases_holds_exactly_the_two_phases() -> None:
+    assert validation_phase_constants.ALL_VALIDATION_PHASES == {
+        validation_phase_constants.EDIT_LANE_PHASE,
+        validation_phase_constants.FULL_GATE_PHASE,
+    }
+
+
+def test_unknown_phase_raises_value_error_naming_the_rejected_value() -> None:
+    with pytest.raises(ValueError, match=UNKNOWN_PHASE_NAME):
+        code_rules_enforcer.validate_content_for_phase(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH, phase=UNKNOWN_PHASE_NAME
+        )
+
+
+def test_validate_content_for_phase_requires_phase_keyword() -> None:
+    with pytest.raises(TypeError):
+        code_rules_enforcer.validate_content_for_phase(SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH)
+
+
+def _full_gate_only_default_kwargs() -> dict[str, object]:
+    return {
+        each_name: DEFAULT
+        for each_name in validation_phase_constants.ALL_FULL_GATE_ONLY_CHECK_NAMES
+    }
+
+
+def _patched_full_gate_only_checks() -> contextlib.AbstractContextManager[dict[str, MagicMock]]:
+    """Return the patch.multiple context manager for the six full-gate-only checks.
+
+    ::
+
+        mypy's patch.multiple stub only accepts an ``Any | str`` target, so a
+        dynamically loaded ``ModuleType`` target needs a local type: ignore.
+    """
+    return patch.multiple(  # type: ignore[call-overload]  # mypy stub rejects ModuleType targets
+        code_rules_enforcer, **_full_gate_only_default_kwargs()
+    )
+
+
+def _configure_full_gate_only_mock_returns(all_mocks: dict[str, MagicMock]) -> None:
+    for each_name, each_mock in all_mocks.items():
+        each_mock.return_value = None if each_name == "advise_cross_skill_duplicate_helper" else []
+
+
+def test_edit_lane_calls_none_of_the_six_full_gate_only_checks() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        code_rules_enforcer.validate_content_for_edit_lane(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        for each_name, each_mock in all_mocks.items():
+            assert each_mock.call_count == 0, f"edit lane must not call {each_name}"
+
+
+def test_full_gate_calls_all_six_full_gate_only_checks() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        code_rules_enforcer.validate_content_for_full_gate(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        for each_name, each_mock in all_mocks.items():
+            assert each_mock.call_count >= 1, f"full gate must call {each_name}"
+
+
+def test_both_phases_report_identical_findings_with_the_six_spied_out() -> None:
+    with _patched_full_gate_only_checks() as all_mocks:
+        _configure_full_gate_only_mock_returns(all_mocks)
+        edit_lane_issues = code_rules_enforcer.validate_content_for_edit_lane(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+        full_gate_issues = code_rules_enforcer.validate_content_for_full_gate(
+            SAMPLE_PYTHON_CONTENT, PRODUCTION_FILE_PATH
+        )
+    assert edit_lane_issues == full_gate_issues
+
+
+def test_no_caller_should_reach_a_phase_less_validator() -> None:
+    assert not hasattr(code_rules_enforcer, "validate_content"), (
+        "validate_content must not survive as a callable on the enforcer module"
+    )
+    enforcer_source = inspect.getsource(code_rules_enforcer)
+    assert re.search(r"\bvalidate_content\(", enforcer_source) is None, (
+        "no call site in code_rules_enforcer.py may reach a phase-less validator"
+    )
+
+
+def test_precheck_selects_the_full_gate() -> None:
+    precheck_source = inspect.getsource(code_rules_enforcer._run_precheck)
+    assert "validate_content_for_full_gate(" in precheck_source, (
+        "the --check precheck must run the full-gate verdict"
+    )
+
+
+def test_codex_patch_issues_selects_the_edit_lane() -> None:
+    """Pin the apply_patch mutation path to the edit-lane verdict."""
+    codex_patch_issues_source = inspect.getsource(code_rules_enforcer._codex_patch_issues)
+    assert "validate_content_for_edit_lane(" in codex_patch_issues_source, (
+        "the apply_patch branch must run the edit-lane verdict"
+    )
+
+
+def test_forecast_full_file_violations_selects_the_edit_lane() -> None:
+    """Pin the full-file forecast pass to the edit-lane verdict."""
+    forecast_source = inspect.getsource(code_rules_enforcer._forecast_full_file_violations)
+    assert "validate_content_for_edit_lane(" in forecast_source, (
+        "the full-file forecast pass must run the edit-lane verdict"
+    )
+
+
+def test_report_blocking_violations_selects_the_edit_lane() -> None:
+    """Pin the PreToolUse Write and Edit main path to the edit-lane verdict."""
+    report_blocking_violations_source = inspect.getsource(
+        code_rules_enforcer._report_blocking_violations
+    )
+    assert "validate_content_for_edit_lane(" in report_blocking_violations_source, (
+        "the PreToolUse Write and Edit main path must run the edit-lane verdict"
+    )
+
+
+def _write_scoped_service_file_with_a_committed_baseline(repository_root: Path) -> Path:
+    repo_test_helpers.init_repository(repository_root)
+    return repo_test_helpers.write_commit_and_stage_change(
+        repository_root,
+        "service.py",
+        "def read_port() -> int:\n    return 0\n",
+        "def read_port() -> int:\n    port_number = 9999\n    return port_number\n",
+    )
+
+
+def test_hook_infrastructure_edit_lane_skips_the_cross_file_duplicate_check() -> None:
+    with patch.object(
+        code_rules_enforcer, "check_duplicate_function_body_across_files"
+    ) as mock_check_duplicate_across_files:
+        mock_check_duplicate_across_files.return_value = []
+        code_rules_enforcer._hook_infrastructure_blocking_issues(
+            SAMPLE_PYTHON_CONTENT,
+            HOOK_INFRASTRUCTURE_FILE_PATH,
+            phase=validation_phase_constants.EDIT_LANE_PHASE,
+        )
+    assert mock_check_duplicate_across_files.call_count == 0, (
+        "the hook-infrastructure edit lane must not call the cross-file duplicate-body check"
+    )
+
+
+def test_hook_infrastructure_full_gate_calls_the_cross_file_duplicate_check() -> None:
+    with patch.object(
+        code_rules_enforcer, "check_duplicate_function_body_across_files"
+    ) as mock_check_duplicate_across_files:
+        mock_check_duplicate_across_files.return_value = []
+        code_rules_enforcer._hook_infrastructure_blocking_issues(
+            SAMPLE_PYTHON_CONTENT,
+            HOOK_INFRASTRUCTURE_FILE_PATH,
+            phase=validation_phase_constants.FULL_GATE_PHASE,
+        )
+    assert mock_check_duplicate_across_files.call_count == 1, (
+        "the hook-infrastructure full gate must still call the cross-file duplicate-body check"
+    )
+
+
+def _write_duplicate_helper_pair_under_a_non_test_named_tempdir() -> tuple[Path, str]:
+    """Write a hook-infra sibling pair under a ``tempfile.mkdtemp()`` root.
+
+    ``tempfile.mkdtemp()`` names its directory ``tmp<random>``, carrying no
+    ``test_`` segment, unlike pytest's own ``tmp_path`` fixture — whose
+    directory embeds the test's name and so reads as a test path to
+    ``is_test_file``'s full-path substring match, silently exempting every
+    check the caller means to exercise.
+    """
+    base_directory = Path(tempfile.mkdtemp())
+    hook_blocking_directory = base_directory / "packages" / "claude-dev-env" / "hooks" / "blocking"
+    hook_blocking_directory.mkdir(parents=True)
+    (hook_blocking_directory / "shipping_helper.py").write_text(
+        _HOOK_MODULE_DUPLICATE_BODY_SOURCE, encoding="utf-8"
+    )
+    return base_directory, str(hook_blocking_directory / "shipping_target.py")
+
+
+def test_full_gate_still_catches_a_helper_duplicated_across_two_hook_modules() -> None:
+    base_directory, target_path = _write_duplicate_helper_pair_under_a_non_test_named_tempdir()
+    try:
+        full_gate_issues = code_rules_enforcer._hook_infrastructure_blocking_issues(
+            _HOOK_MODULE_DUPLICATE_BODY_SOURCE,
+            target_path,
+            phase=validation_phase_constants.FULL_GATE_PHASE,
+        )
+        edit_lane_issues = code_rules_enforcer._hook_infrastructure_blocking_issues(
+            _HOOK_MODULE_DUPLICATE_BODY_SOURCE,
+            target_path,
+            phase=validation_phase_constants.EDIT_LANE_PHASE,
+        )
+    finally:
+        shutil.rmtree(base_directory, ignore_errors=False)
+
+    assert any("duplicates" in each_issue for each_issue in full_gate_issues), (
+        "the full gate must still catch a helper duplicated across two hook "
+        f"modules, got: {full_gate_issues!r}"
+    )
+    assert not any("duplicates" in each_issue for each_issue in edit_lane_issues), (
+        "the edit lane must not run the cross-file duplicate-body check against "
+        f"hook infrastructure, got: {edit_lane_issues!r}"
+    )
+
+
+def test_gate_running_selects_the_full_gate(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    repository_root.mkdir()
+    file_path = _write_scoped_service_file_with_a_committed_baseline(repository_root)
+
+    loaded_validate_content = enforcer_loading.load_validate_content_for_full_gate()
+    assert loaded_validate_content.__name__ == "validate_content_for_full_gate"
+
+    scoped_violations = gate_running._scoped_violations_for_file(
+        validate_content=loaded_validate_content,
+        resolved_path=file_path,
+        repository_root=repository_root,
+        all_added_lines_for_file={2, 3},
+        should_read_staged_content=True,
+    )
+    assert scoped_violations is not None
+    blocking_violations, _advisory_violations = scoped_violations
+    assert any("9999" in each_issue for each_issue in blocking_violations)
+
+
+ALL_CHECK_FUNCTION_NAME_PREFIXES = ("check_", "advise_")
+
+
+def _check_names_called_in(enforcer_function_name: str) -> set[str]:
+    """Return the check-function names called directly inside a phase router.
+
+    Parses the router's own source and collects every direct call to a
+    module-level name beginning with a check prefix, so a roster constant can
+    assert against the calls production really makes rather than against a
+    second hand-written literal.
+
+    Args:
+        enforcer_function_name: The attribute name of the router on the
+            enforcer module, such as ``_python_full_gate_only_issues``.
+
+    Returns:
+        The set of check-function names the router calls directly.
+    """
+    router_source = textwrap.dedent(
+        inspect.getsource(getattr(code_rules_enforcer, enforcer_function_name))
+    )
+    return {
+        each_node.func.id
+        for each_node in ast.walk(ast.parse(router_source))
+        if isinstance(each_node, ast.Call)
+        and isinstance(each_node.func, ast.Name)
+        and each_node.func.id.startswith(ALL_CHECK_FUNCTION_NAME_PREFIXES)
+    }
+
+
+def test_full_gate_only_roster_matches_the_checks_the_router_calls() -> None:
+    """The roster constant tracks the calls in _python_full_gate_only_issues."""
+    assert (
+        _check_names_called_in("_python_full_gate_only_issues")
+        == validation_phase_constants.ALL_FULL_GATE_ONLY_CHECK_NAMES
+    ), "ALL_FULL_GATE_ONLY_CHECK_NAMES must name exactly the router's own calls"
+
+
+def test_hook_infrastructure_edit_lane_roster_matches_the_checks_the_router_calls() -> None:
+    """The roster constant tracks the always-run calls in the hook-infrastructure router."""
+    all_always_run_check_names = _check_names_called_in(
+        "_hook_infrastructure_blocking_issues"
+    ) - validation_phase_constants.ALL_FULL_GATE_ONLY_CHECK_NAMES
+    assert (
+        all_always_run_check_names
+        == validation_phase_constants.ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES
+    ), "ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES must name exactly the router's own calls"

package/hooks/blocking/test_fable_spawn_gate.py

@@ -72,7 +72,7 @@ _ADVISOR_LIFECYCLE_TEXT = (_ADVISOR_REFERENCE_DIR / "lifecycle.md").read_text(
 _ADVISOR_WARM_UP_TEXT = (_ADVISOR_REFERENCE_DIR / "warm-up.md").read_text(
     encoding="utf-8"
 )
-_ALL_CONSUMING_SKILL_NAMES = ("team-advisor", "orchestrator", "orchestrator-refresh")
+_ALL_CONSUMING_SKILL_NAMES = ("team-advisor",)
 _ALL_CONSUMING_SKILL_PATHS = tuple(
     _PACKAGE_ROOT / ".agents" / "skills" / each_skill_name / "SKILL.md"
     for each_skill_name in _ALL_CONSUMING_SKILL_NAMES

package/hooks/blocking/test_pre_tool_use_dispatcher.py

@@ -734,16 +734,31 @@ def test_dispatcher_multi_edit_applies_only_group_b() -> None:
     )
 
 
-def test_proceed_after_run_all_validators_removal_allows() -> None:
-    """The PreToolUse dispatcher allows a Python edit that the removed gate would have processed.
-
-    The inline run_all_validators runner was a PostToolUse gate removed in Stage 4;
-    it was never a PreToolUse hook and never hosted by the PreToolUse dispatcher.
-    A Python Write payload that run_all_validators would have flagged (mypy errors, for
-    instance) still produces ALLOW from the PreToolUse dispatcher because the PreToolUse
-    dispatcher covers only its 23 hosted blocking hooks — none of which includes the
-    validators runner.
+def _assert_roster_names_no_run_all_validators_entry() -> None:
+    """Assert no hosted-roster ``script_relative_path`` names run_all_validators."""
+    all_roster_script_paths = {
+        each_entry.script_relative_path for each_entry in ALL_HOSTED_HOOK_ENTRIES
+    }
+    assert not any(
+        "run_all_validators" in each_script_path
+        for each_script_path in all_roster_script_paths
+    ), (
+        "ALL_HOSTED_HOOK_ENTRIES must name no run_all_validators entry, got: "
+        f"{sorted(all_roster_script_paths)}"
+    )
+
+
+def test_run_all_validators_is_not_hosted_by_pre_tool_use_dispatcher() -> None:
+    """The main PreToolUse dispatcher's hosted roster names no run_all_validators entry.
+
+    ``hooks.json`` registers the ``run_all_validators`` runner as its own
+    PreToolUse ``Write|Edit`` command, separate from the main dispatcher. A
+    Python Write payload that ``run_all_validators`` would flag (a type error,
+    for instance) still produces ALLOW from the main dispatcher, because its
+    roster carries no entry for that runner.
     """
+    _assert_roster_names_no_run_all_validators_entry()
+
     python_content_with_type_error = (
         "def add_one(value: int) -> int:\n"
         "    return value + 1\n\n\n"
@@ -754,8 +769,8 @@ def test_proceed_after_run_all_validators_removal_allows() -> None:
     is_deny, _reason = _parse_hook_decision(dispatcher_result)
     assert not is_deny, (
         "PreToolUse dispatcher must allow a Python Write with a type error — "
-        "mypy validation is PostToolUse-only; the removed run_all_validators gate "
-        "was never a PreToolUse hook"
+        "run_all_validators runs as its own separate PreToolUse command, not "
+        "through this dispatcher's roster"
     )
     assert dispatcher_result.returncode == 0, (
         f"Dispatcher must exit 0, got {dispatcher_result.returncode}"

package/hooks/blocking/test_shell_substitution_blocker.py

@@ -122,3 +122,72 @@ def test_allows_arithmetic_expansion() -> None:
         "tool_input": {"command": "echo $((2+2))"},
     }
     assert _run_hook(payload).stdout == ""
+
+
+def test_allows_arithmetic_expansion_with_nested_parens() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $(( (1+2) * 3 ))"},
+    }
+    assert _run_hook(payload).stdout == ""
+
+
+def test_allows_arithmetic_expansion_whose_body_bash_itself_rejects() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $((echo hi))"},
+    }
+    assert _run_hook(payload).stdout == ""
+
+
+def test_allows_arithmetic_lookalike_inside_single_quotes() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo '$((cd /tmp) && pwd)'"},
+    }
+    assert _run_hook(payload).stdout == ""
+
+
+def test_denies_subshell_disguised_as_arithmetic_expansion() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $((cd /tmp) && pwd)"},
+    }
+    response = json.loads(_run_hook(payload).stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_denies_parenthesized_command_word_disguised_as_arithmetic() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $((1+2) )"},
+    }
+    response = json.loads(_run_hook(payload).stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_denies_command_substitution_nested_inside_arithmetic_expansion() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $(( $(id -u) + 1 ))"},
+    }
+    response = json.loads(_run_hook(payload).stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_denies_backtick_substitution_nested_inside_arithmetic_expansion() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $(( `id -u` + 1 ))"},
+    }
+    response = json.loads(_run_hook(payload).stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_denies_nested_command_substitution_without_arithmetic() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "echo $(echo $(whoami))"},
+    }
+    response = json.loads(_run_hook(payload).stdout)
+    assert response["hookSpecificOutput"]["permissionDecision"] == "deny"

package/hooks/hooks.json

@@ -171,7 +171,7 @@
           },
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/task_list_loop_starter.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/task_tool_prompt.py",
             "timeout": 10
           },
           {

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -6,6 +6,13 @@ Extracted from code_rules_enforcer.py to satisfy the constants-location rule.
 import re
 import tokenize
 
+from hooks_constants.validation_phase_constants import (  # noqa: F401  re-exported for code_rules_enforcer.py
+    ALL_VALIDATION_PHASES,
+    EDIT_LANE_PHASE,
+    FULL_GATE_PHASE,
+    UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
+)
+
 ALL_PYTHON_TOKENIZE_FAILURE_EXCEPTIONS: tuple[type[BaseException], ...] = (
     tokenize.TokenError,
     IndentationError,

package/hooks/hooks_constants/shell_substitution_blocker_constants.py

@@ -41,7 +41,10 @@ PERMISSION_DECISION_KEY = "permissionDecision"
 DENY_DECISION = "deny"
 PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
 
-DOLLAR_PAREN_PATTERN = re.compile(r"\$\((?!\()")
+DOLLAR_PAREN_PATTERN = re.compile(r"\$\(")
+OPEN_PAREN_CHARACTER = "("
+CLOSE_PAREN_CHARACTER = ")"
+PAREN_DEPTH_AFTER_DOUBLE_OPEN = 2
 EVEN_BACKSLASH_BACKTICK_PATTERN = re.compile(r"(?<!\\)(?:\\\\)*`")
 PROCESS_SUBSTITUTION_PATTERN = re.compile(r"[<>]\(")
 SINGLE_QUOTED_RUN_PATTERN = re.compile(r"'[^']*'")

package/hooks/hooks_constants/task_tool_prompt_constants.py

@@ -0,0 +1,13 @@
+"""Directive text for the task_tool_prompt SessionStart hook."""
+
+from __future__ import annotations
+
+__all__ = [
+    "TASK_TOOL_DIRECTIVE",
+]
+
+TASK_TOOL_DIRECTIVE = (
+    "TASK TRACKING: Track this session's work with the session's task or todo "
+    "tracking tool, whichever this host provides. Create tasks at the start "
+    "of the session, then update them as work proceeds."
+)

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,12 +17,16 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
+    ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
+    EDIT_LANE_PHASE,
+    FULL_GATE_PHASE,
     FUNCTION_WITH_JSDOC_PATTERN,
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
+    UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
 )
 
 
@@ -98,3 +102,11 @@ def test_schema_property_key_pattern_matches_only_the_options_key() -> None:
 def test_constants_module_suffix_and_config_directory_segment_are_defined() -> None:
     assert CONSTANTS_MODULE_SUFFIX == "_constants.py"
     assert CONFIG_DIRECTORY_SEGMENT == "config"
+
+
+def test_validation_phase_constants_are_reexported_and_render() -> None:
+    assert ALL_VALIDATION_PHASES == {EDIT_LANE_PHASE, FULL_GATE_PHASE}
+    rendered_message = UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE.format(
+        phase="bogus_phase", all_phases=sorted(ALL_VALIDATION_PHASES)
+    )
+    assert "bogus_phase" in rendered_message

package/hooks/hooks_constants/validation_phase_constants.py

@@ -0,0 +1,34 @@
+"""Constants for the validate_content edit-lane and full-gate phase split.
+
+The edit lane and the full gate share every check except six that read
+sibling modules from disk. These names identify each phase, name the checks
+the full gate alone runs, name the hook-infrastructure checks the edit lane
+still runs, and template the error for an unrecognized phase.
+"""
+
+EDIT_LANE_PHASE: str = "edit_lane"
+FULL_GATE_PHASE: str = "full_gate"
+ALL_VALIDATION_PHASES: frozenset[str] = frozenset({EDIT_LANE_PHASE, FULL_GATE_PHASE})
+
+ALL_FULL_GATE_ONLY_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_duplicate_function_body_across_files",
+        "advise_cross_skill_duplicate_helper",
+        "check_public_function_missing_paired_test",
+        "check_test_file_omits_module_public_function",
+        "check_orphan_css_classes",
+        "check_config_duplicate_path_anchor",
+    }
+)
+
+ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES: frozenset[str] = frozenset(
+    {
+        "check_same_file_inline_duplicate_body",
+        "check_zero_payload_function_alias",
+        "check_unanchored_command_dispatch",
+    }
+)
+
+UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE: str = (
+    "unrecognized validation phase {phase!r}; expected one of {all_phases}"
+)

package/hooks/session/task_tool_prompt.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python3
+"""SessionStart hook — direct the session to track work with its task tool.
+
+At session start this hook emits an ``additionalContext`` directive asking
+the session to track its work with the task or todo tracking tool its host
+provides: create tasks at the start of the session, then update them as
+work proceeds.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import _path_setup  # noqa: F401
+
+from hooks_constants.task_tool_prompt_constants import TASK_TOOL_DIRECTIVE
+
+
+def build_session_directive() -> str:
+    """Return the task-tool directive emitted at session start."""
+    return TASK_TOOL_DIRECTIVE
+
+
+def main() -> None:
+    """Emit the task-tool directive as SessionStart additionalContext."""
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": build_session_directive(),
+        }
+    }
+    sys.stdout.write(json.dumps(payload) + "\n")
+
+
+if __name__ == "__main__":
+    main()