claude-dev-env 2.9.0 → 2.11.0

package/hooks/observability/prose_matcher_advisory.py

@@ -0,0 +1,237 @@
+"""Privacy-safe advisory telemetry and precision classification for prose matchers.
+
+Emits candidate records with matcher id, surface, hashed context fingerprint,
+and optional human label. Classifies each matcher as keep, narrow, drop, or
+remain advisory when the labeled sample floor is unmet. Never hard-blocks from
+historical labels alone.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Mapping, Sequence
+
+from hooks_constants.prose_matcher_precision_constants import (
+    ADVISORY_LOG_RELATIVE_PATH,
+    ALL_KNOWN_MATCHER_IDS,
+    ALL_LABEL_DECISIONS,
+    CLASSIFICATION_ADVISORY,
+    CLASSIFICATION_DROP,
+    CLASSIFICATION_KEEP,
+    CLASSIFICATION_NARROW,
+    CONTEXT_FINGERPRINT_HEX_LENGTH,
+    DECISION_FALSE_POSITIVE,
+    DECISION_TRUE_POSITIVE,
+    DECISION_UNLABELED,
+    KEEP_PRECISION_FLOOR,
+    NARROW_PRECISION_FLOOR,
+    SAMPLE_FLOOR_PER_MATCHER,
+)
+
+
+def context_fingerprint(context_text: str) -> str:
+    """Return a short hex fingerprint of context text (never the raw prose).
+
+    Args:
+        context_text: Snippet around a matcher hit.
+
+    Returns:
+        Lowercase hex digest truncated for log size.
+    """
+    digest = hashlib.sha256(context_text.encode("utf-8")).hexdigest()
+    return digest[:CONTEXT_FINGERPRINT_HEX_LENGTH]
+
+
+def build_candidate_record(
+    matcher_id: str,
+    surface: str,
+    context_text: str,
+    decision: str = DECISION_UNLABELED,
+) -> dict[str, object]:
+    """Build one privacy-safe advisory candidate record.
+
+    Args:
+        matcher_id: Known matcher identifier.
+        surface: Tool or reply surface name.
+        context_text: Local snippet used only for hashing.
+        decision: Label decision (true_positive / false_positive / unlabeled).
+
+    Returns:
+        Record ready to append to the advisory JSONL log.
+
+    Raises:
+        ValueError: When matcher_id or decision is unknown.
+    """
+    if matcher_id not in ALL_KNOWN_MATCHER_IDS:
+        raise ValueError(f"unknown matcher_id: {matcher_id!r}")
+    if decision not in ALL_LABEL_DECISIONS:
+        raise ValueError(f"unknown decision: {decision!r}")
+    return {
+        "matcher_id": matcher_id,
+        "surface": surface,
+        "context_fingerprint": context_fingerprint(context_text),
+        "decision": decision,
+        "recorded_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def advisory_log_path(home_directory: Path | None = None) -> Path:
+    """Return the advisory log path under the user home.
+
+    Args:
+        home_directory: Optional home override for tests.
+
+    Returns:
+        Absolute path to the JSONL log file.
+    """
+    home_root = home_directory if home_directory is not None else Path.home()
+    return home_root / ADVISORY_LOG_RELATIVE_PATH
+
+
+def emit_advisory_candidate(
+    matcher_id: str,
+    surface: str,
+    context_text: str,
+    decision: str = DECISION_UNLABELED,
+    home_directory: Path | None = None,
+) -> dict[str, object]:
+    """Append one advisory candidate and return the record.
+
+    Args:
+        matcher_id: Known matcher identifier.
+        surface: Tool or reply surface name.
+        context_text: Snippet hashed into the fingerprint.
+        decision: Optional label decision.
+        home_directory: Optional home override for tests.
+
+    Returns:
+        The written candidate record.
+    """
+    candidate_record = build_candidate_record(
+        matcher_id, surface, context_text, decision
+    )
+    log_path = advisory_log_path(home_directory)
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a", encoding="utf-8") as log_file:
+        log_file.write(json.dumps(candidate_record) + "\n")
+    return candidate_record
+
+
+def precision_for_labeled_candidates(
+    all_candidates: Sequence[Mapping[str, object]],
+) -> float | None:
+    """Return precision among labeled candidates, or None when none are labeled.
+
+    Args:
+        all_candidates: Candidate records for one matcher.
+
+    Returns:
+        true_positive / (true_positive + false_positive), or None when no labels.
+    """
+    true_positive_count = 0
+    false_positive_count = 0
+    for each_candidate in all_candidates:
+        decision = each_candidate.get("decision")
+        if decision == DECISION_TRUE_POSITIVE:
+            true_positive_count += 1
+        elif decision == DECISION_FALSE_POSITIVE:
+            false_positive_count += 1
+    labeled_count = true_positive_count + false_positive_count
+    if labeled_count == 0:
+        return None
+    return true_positive_count / labeled_count
+
+
+def classify_matcher(
+    all_candidates: Sequence[Mapping[str, object]],
+    sample_floor: int = SAMPLE_FLOOR_PER_MATCHER,
+    keep_precision_floor: float = KEEP_PRECISION_FLOOR,
+    narrow_precision_floor: float = NARROW_PRECISION_FLOOR,
+) -> dict[str, object]:
+    """Classify a matcher from labeled evidence.
+
+    Args:
+        all_candidates: Candidate records for one matcher.
+        sample_floor: Minimum labeled count before leave advisory.
+        keep_precision_floor: Precision required to keep.
+        narrow_precision_floor: Precision required to narrow instead of drop.
+
+    Returns:
+        Classification record with status, labeled_count, precision, and
+        whether the production observation window must restart.
+    """
+    labeled_count = sum(
+        1
+        for each_candidate in all_candidates
+        if each_candidate.get("decision")
+        in (DECISION_TRUE_POSITIVE, DECISION_FALSE_POSITIVE)
+    )
+    precision = precision_for_labeled_candidates(all_candidates)
+    if labeled_count < sample_floor:
+        return {
+            "status": CLASSIFICATION_ADVISORY,
+            "labeled_count": labeled_count,
+            "precision": precision,
+            "restart_observation_window": False,
+            "reason": "below sample floor",
+        }
+    assert precision is not None
+    if precision >= keep_precision_floor:
+        return {
+            "status": CLASSIFICATION_KEEP,
+            "labeled_count": labeled_count,
+            "precision": precision,
+            "restart_observation_window": False,
+            "reason": "meets keep precision floor",
+        }
+    if precision >= narrow_precision_floor:
+        return {
+            "status": CLASSIFICATION_NARROW,
+            "labeled_count": labeled_count,
+            "precision": precision,
+            "restart_observation_window": True,
+            "reason": "meets narrow floor; restart observation window",
+        }
+    return {
+        "status": CLASSIFICATION_DROP,
+        "labeled_count": labeled_count,
+        "precision": precision,
+        "restart_observation_window": False,
+        "reason": "below narrow precision floor",
+    }
+
+
+def classify_all_known_matchers(
+    all_candidates: Sequence[Mapping[str, object]],
+    sample_floor: int = SAMPLE_FLOOR_PER_MATCHER,
+    keep_precision_floor: float = KEEP_PRECISION_FLOOR,
+    narrow_precision_floor: float = NARROW_PRECISION_FLOOR,
+) -> dict[str, dict[str, object]]:
+    """Classify every known matcher; missing matchers stay advisory.
+
+    Args:
+        all_candidates: Mixed candidates across matchers.
+        sample_floor: Minimum labeled count before leave advisory.
+        keep_precision_floor: Precision required to keep.
+        narrow_precision_floor: Precision required to narrow instead of drop.
+
+    Returns:
+        Mapping of matcher_id to classification record.
+    """
+    classification_by_matcher: dict[str, dict[str, object]] = {}
+    for each_matcher_id in ALL_KNOWN_MATCHER_IDS:
+        all_matcher_candidates = [
+            each_candidate
+            for each_candidate in all_candidates
+            if each_candidate.get("matcher_id") == each_matcher_id
+        ]
+        classification_by_matcher[each_matcher_id] = classify_matcher(
+            all_matcher_candidates,
+            sample_floor=sample_floor,
+            keep_precision_floor=keep_precision_floor,
+            narrow_precision_floor=narrow_precision_floor,
+        )
+    return classification_by_matcher

package/hooks/observability/test_prose_matcher_advisory.py

@@ -0,0 +1,143 @@
+"""Tests for prose matcher advisory telemetry and precision classification."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants.prose_matcher_precision_constants import (  # noqa: E402
+    CLASSIFICATION_ADVISORY,
+    CLASSIFICATION_DROP,
+    CLASSIFICATION_KEEP,
+    CLASSIFICATION_NARROW,
+    DECISION_FALSE_POSITIVE,
+    DECISION_TRUE_POSITIVE,
+    DECISION_UNLABELED,
+    MATCHER_ID_HEDGING_WORD,
+    MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+    SAMPLE_FLOOR_PER_MATCHER,
+)
+from observability.prose_matcher_advisory import (  # noqa: E402
+    build_candidate_record,
+    classify_all_known_matchers,
+    classify_matcher,
+    context_fingerprint,
+    emit_advisory_candidate,
+)
+
+
+def test_context_fingerprint_is_stable_and_not_raw_text() -> None:
+    fingerprint = context_fingerprint("utilize the cache layer now")
+    assert fingerprint == context_fingerprint("utilize the cache layer now")
+    assert "utilize" not in fingerprint
+    assert len(fingerprint) == 16
+
+
+def test_build_candidate_record_rejects_unknown_matcher() -> None:
+    with pytest.raises(ValueError, match="unknown matcher"):
+        build_candidate_record("unknown", "Write", "snippet")
+
+
+def test_emit_advisory_candidate_writes_privacy_safe_jsonl(tmp_path: Path) -> None:
+    record = emit_advisory_candidate(
+        MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+        "Write",
+        "Please utilize the cache",
+        home_directory=tmp_path,
+    )
+    assert record["matcher_id"] == MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD
+    assert record["surface"] == "Write"
+    assert "utilize" not in json.dumps(record)
+    log_path = tmp_path / ".claude" / "logs" / "prose-matcher-advisory.jsonl"
+    assert log_path.is_file()
+    logged = json.loads(log_path.read_text(encoding="utf-8").strip())
+    assert logged["context_fingerprint"] == record["context_fingerprint"]
+    assert logged["decision"] == DECISION_UNLABELED
+
+
+def test_below_sample_floor_remains_advisory() -> None:
+    all_candidates = [
+        {
+            "matcher_id": MATCHER_ID_HEDGING_WORD,
+            "decision": DECISION_TRUE_POSITIVE,
+        }
+        for _ in range(SAMPLE_FLOOR_PER_MATCHER - 1)
+    ]
+    classification = classify_matcher(all_candidates)
+    assert classification["status"] == CLASSIFICATION_ADVISORY
+    assert classification["restart_observation_window"] is False
+
+
+def test_keep_when_precision_meets_floor() -> None:
+    all_candidates = [
+        {"decision": DECISION_TRUE_POSITIVE}
+        for _ in range(SAMPLE_FLOOR_PER_MATCHER)
+    ]
+    classification = classify_matcher(all_candidates)
+    assert classification["status"] == CLASSIFICATION_KEEP
+    assert classification["precision"] == 1.0
+    assert classification["restart_observation_window"] is False
+
+
+def test_narrow_restarts_observation_window() -> None:
+    all_candidates = (
+        [{"decision": DECISION_TRUE_POSITIVE} for _ in range(15)]
+        + [{"decision": DECISION_FALSE_POSITIVE} for _ in range(15)]
+    )
+    classification = classify_matcher(all_candidates)
+    assert classification["status"] == CLASSIFICATION_NARROW
+    assert classification["restart_observation_window"] is True
+
+
+def test_drop_when_precision_below_narrow_floor() -> None:
+    all_candidates = (
+        [{"decision": DECISION_TRUE_POSITIVE} for _ in range(5)]
+        + [{"decision": DECISION_FALSE_POSITIVE} for _ in range(25)]
+    )
+    classification = classify_matcher(all_candidates)
+    assert classification["status"] == CLASSIFICATION_DROP
+    assert classification["restart_observation_window"] is False
+
+
+def test_classify_all_known_matchers_covers_each_matcher() -> None:
+    all_candidates = [
+        {
+            "matcher_id": MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+            "decision": DECISION_TRUE_POSITIVE,
+        }
+    ]
+    classification_by_matcher = classify_all_known_matchers(all_candidates)
+    assert set(classification_by_matcher) == {
+        MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+        MATCHER_ID_HEDGING_WORD,
+    }
+    assert (
+        classification_by_matcher[MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD]["status"]
+        == CLASSIFICATION_ADVISORY
+    )
+    assert (
+        classification_by_matcher[MATCHER_ID_HEDGING_WORD]["status"]
+        == CLASSIFICATION_ADVISORY
+    )
+
+
+def test_classification_never_returns_hard_block_status() -> None:
+    all_candidates = [
+        {"decision": DECISION_TRUE_POSITIVE}
+        for _ in range(SAMPLE_FLOOR_PER_MATCHER)
+    ]
+    classification = classify_matcher(all_candidates)
+    assert classification["status"] in {
+        CLASSIFICATION_KEEP,
+        CLASSIFICATION_NARROW,
+        CLASSIFICATION_DROP,
+        CLASSIFICATION_ADVISORY,
+    }
+    assert "block" not in str(classification["status"]).lower()

package/hooks/session/CLAUDE.md

@@ -1,6 +1,6 @@
 # hooks/session
 
-SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, and clearing PR-author swap state at shutdown.
+SessionStart and SessionEnd hooks for per-session setup and cleanup: removing stale session and plugin-data directories at startup, detecting unregistered repositories, starting the session's task-list maintenance loop, injecting working-style guidance, and clearing PR-author swap state at shutdown.
 
 ## Key files
 
@@ -12,11 +12,19 @@ SessionStart and SessionEnd hooks for per-session setup and cleanup: removing st
 | `plugin_data_dir_cleanup.py` | SessionStart | Removes empty plugin data directories at startup to prevent `EEXIST` when Claude Code recreates them |
 | `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
 | `task_list_loop_starter.py` | SessionStart | Emits an `additionalContext` directive telling Claude to keep the task list current on a 10-minute cadence, starting the `/loop` skill when one is not already running. Writes nothing and runs no tools itself. |
+| `orchestrator_auto_starter.py` | SessionStart | Opt-in (`CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED`) consumer of the shared SessionStart injector; emits orchestrator skill context when enabled. Manual `/orchestrator` unchanged. |
+| `issue_tracker_session_starter.py` | SessionStart | Opt-in (`CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED`) and repository-gated (git root in `~/.claude/project-paths.json`) issue-tracker skill context. |
+| `_path_setup.py` | — | Inserts the hooks directory on `sys.path` so SessionStart scripts import `hooks_constants` with top-level imports. |
+| `test_orchestrator_auto_starter.py` | — | Tests for `orchestrator_auto_starter.py` |
+| `test_issue_tracker_session_starter.py` | — | Tests for `issue_tracker_session_starter.py` |
+| `working_style_prompt.py` | SessionStart | Emits an `additionalContext` block with the fixed working-style prompt (running ledger, plain English, outcome-first finish, scope discipline). Writes nothing and runs no tools itself. |
 | `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
 | `test_session_edit_tracker_cleanup.py` | — | Tests for `session_edit_tracker_cleanup.py` |
 | `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
 | `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
 | `test_task_list_loop_starter.py` | — | Tests for `task_list_loop_starter.py` |
+| `test__path_setup.py` | — | Tests for `_path_setup.py` |
+| `test_working_style_prompt.py` | — | Tests for `working_style_prompt.py` |
 
 ## Conventions
 

package/hooks/session/_path_setup.py

@@ -0,0 +1,13 @@
+"""Add the hooks directory to sys.path for session entry-point scripts.
+
+Importing this module inserts the hooks directory (this file's parent) at the
+front of sys.path so a SessionStart script under session/ can import
+hooks_constants with every import kept at module top.
+"""
+
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)

package/hooks/session/issue_tracker_session_starter.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""SessionStart hook — repository-gated issue-tracker context via shared injector.
+
+Default off. When CLAUDE_ISSUE_TRACKER_SESSION_STARTER_ENABLED is set and the
+session cwd's git root appears in ~/.claude/project-paths.json, emit an
+additionalContext directive for the issue-tracker skill. Missing registry or
+unregistered repos fail closed with no output.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.issue_tracker_session_starter_constants import (  # noqa: E402
+    ALL_ISSUE_TRACKER_STARTER_ENABLED_ENV_VALUES,
+    ISSUE_TRACKER_SESSION_START_DIRECTIVE,
+    ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR,
+    ISSUE_TRACKER_STARTER_TIMEOUT_MILLISECONDS,
+)
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+from hooks_constants.project_paths_reader import (  # noqa: E402
+    find_git_root,
+    load_registry,
+    registry_contains_path,
+)
+from hooks_constants.session_start_injector import (  # noqa: E402
+    InjectorConfiguration,
+    build_additional_context_payload,
+    inject_session_start_context,
+)
+from hooks_constants.session_start_injector_constants import (  # noqa: E402
+    ALL_KNOWN_SESSION_START_SOURCES,
+)
+
+
+def issue_tracker_session_starter_enabled_in_environment() -> bool:
+    """Return True only when the opt-in env var holds an enabled value."""
+    raw_setting = os.environ.get(ISSUE_TRACKER_SESSION_STARTER_ENABLED_ENV_VAR, "")
+    return raw_setting.strip().lower() in ALL_ISSUE_TRACKER_STARTER_ENABLED_ENV_VALUES
+
+
+def repository_is_registered(
+    working_directory: str,
+    registry_by_name: dict[str, str],
+) -> bool:
+    """Return True when cwd git root is a value in the project-paths registry.
+
+    Missing registry, missing git root, or unregistered root fail closed.
+
+    Args:
+        working_directory: Session cwd used to locate the git root.
+        registry_by_name: Name-to-path map; empty map fails closed.
+    """
+    if not registry_by_name:
+        return False
+    git_root = find_git_root(working_directory)
+    if git_root is None:
+        return False
+    return registry_contains_path(registry_by_name, git_root)
+
+
+def build_issue_tracker_injector_configuration(
+    timeout_milliseconds: int,
+) -> InjectorConfiguration:
+    """Build injector config with the issue-tracker directive per known source.
+
+    Args:
+        timeout_milliseconds: Injector budget; zero or less yields timeout status.
+    """
+    context_by_source = {
+        each_source: ISSUE_TRACKER_SESSION_START_DIRECTIVE
+        for each_source in ALL_KNOWN_SESSION_START_SOURCES
+    }
+    return InjectorConfiguration(
+        is_enabled=True,
+        timeout_milliseconds=timeout_milliseconds,
+        context_by_source=context_by_source,
+        default_context_for_unknown="",
+    )
+
+
+def run_issue_tracker_session_starter(
+    payload_by_key: dict[str, object],
+    is_enabled: bool,
+    is_repository_eligible: bool,
+    timeout_milliseconds: int,
+) -> dict[str, str]:
+    """Return additionalContext when opt-in and repo gate both pass, else empty.
+
+    Args:
+        payload_by_key: Parsed SessionStart payload.
+        is_enabled: When False, return empty without calling the injector.
+        is_repository_eligible: When False, return empty without calling the injector.
+        timeout_milliseconds: Injector timeout budget.
+
+    Returns:
+        ``{"additionalContext": ...}`` when injected, else ``{}``.
+    """
+    if not is_enabled or not is_repository_eligible:
+        return {}
+    configuration = build_issue_tracker_injector_configuration(timeout_milliseconds)
+    injection_result = inject_session_start_context(payload_by_key, configuration)
+    return build_additional_context_payload(injection_result)
+
+
+def main() -> None:
+    """Emit issue-tracker additionalContext when opt-in and registry gate pass."""
+    payload_by_key = read_hook_input_dictionary_from_stdin()
+    if payload_by_key is None:
+        return
+    is_enabled = issue_tracker_session_starter_enabled_in_environment()
+    is_repository_eligible = (
+        repository_is_registered(os.getcwd(), load_registry()) if is_enabled else False
+    )
+    payload = run_issue_tracker_session_starter(
+        payload_by_key,
+        is_enabled,
+        is_repository_eligible,
+        ISSUE_TRACKER_STARTER_TIMEOUT_MILLISECONDS,
+    )
+    if payload:
+        print(json.dumps(payload))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/orchestrator_auto_starter.py

@@ -0,0 +1,100 @@
+#!/usr/bin/env python3
+"""SessionStart hook — opt-in orchestrator context via shared injector.
+
+Default off. When CLAUDE_ORCHESTRATOR_AUTO_STARTER_ENABLED is set, emit an
+additionalContext directive that points the session at the orchestrator skill.
+Disabled paths exit without calling the injector (no timeout budget spent).
+
+Manual /orchestrator and the orchestrator agent definition are unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.orchestrator_auto_starter_constants import (  # noqa: E402
+    ALL_ORCHESTRATOR_STARTER_ENABLED_ENV_VALUES,
+    ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR,
+    ORCHESTRATOR_SESSION_START_DIRECTIVE,
+    ORCHESTRATOR_STARTER_TIMEOUT_MILLISECONDS,
+)
+from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
+    read_hook_input_dictionary_from_stdin,
+)
+from hooks_constants.session_start_injector import (  # noqa: E402
+    InjectorConfiguration,
+    build_additional_context_payload,
+    inject_session_start_context,
+)
+from hooks_constants.session_start_injector_constants import (  # noqa: E402
+    ALL_KNOWN_SESSION_START_SOURCES,
+)
+
+
+def orchestrator_auto_starter_enabled_in_environment() -> bool:
+    """Return True only when the opt-in env var holds an enabled value."""
+    raw_setting = os.environ.get(ORCHESTRATOR_AUTO_STARTER_ENABLED_ENV_VAR, "")
+    return raw_setting.strip().lower() in ALL_ORCHESTRATOR_STARTER_ENABLED_ENV_VALUES
+
+
+def build_orchestrator_injector_configuration(
+    timeout_milliseconds: int,
+) -> InjectorConfiguration:
+    """Build injector config that injects the orchestrator directive per source.
+
+    Args:
+        timeout_milliseconds: Injector budget; zero or less yields timeout status.
+    """
+    context_by_source = {
+        each_source: ORCHESTRATOR_SESSION_START_DIRECTIVE
+        for each_source in ALL_KNOWN_SESSION_START_SOURCES
+    }
+    return InjectorConfiguration(
+        is_enabled=True,
+        timeout_milliseconds=timeout_milliseconds,
+        context_by_source=context_by_source,
+        default_context_for_unknown="",
+    )
+
+
+def run_orchestrator_auto_starter(
+    payload_by_key: dict[str, object],
+    is_enabled: bool,
+    timeout_milliseconds: int,
+) -> dict[str, str]:
+    """Return additionalContext payload when opt-in injects, else empty dict.
+
+    Args:
+        payload_by_key: Parsed SessionStart payload.
+        is_enabled: When False, return empty without calling the injector.
+        timeout_milliseconds: Injector timeout budget.
+
+    Returns:
+        ``{"additionalContext": ...}`` when injected, else ``{}``.
+    """
+    if not is_enabled:
+        return {}
+    configuration = build_orchestrator_injector_configuration(timeout_milliseconds)
+    injection_result = inject_session_start_context(payload_by_key, configuration)
+    return build_additional_context_payload(injection_result)
+
+
+def main() -> None:
+    """Emit orchestrator additionalContext when opt-in is enabled; else exit 0."""
+    payload_by_key = read_hook_input_dictionary_from_stdin()
+    if payload_by_key is None:
+        return
+    payload = run_orchestrator_auto_starter(payload_by_key, orchestrator_auto_starter_enabled_in_environment(), ORCHESTRATOR_STARTER_TIMEOUT_MILLISECONDS)
+    if payload:
+        print(json.dumps(payload))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test__path_setup.py

@@ -0,0 +1,28 @@
+"""Tests for session/_path_setup path injection."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+
+import hooks_constants
+
+
+def test_path_setup_puts_hooks_root_on_sys_path() -> None:
+    session_dir = Path(__file__).resolve().parent
+    hooks_root = str(session_dir.parent)
+    path_setup_file = session_dir / "_path_setup.py"
+    if hooks_root in sys.path:
+        sys.path.remove(hooks_root)
+
+    specification = importlib.util.spec_from_file_location(
+        "session_path_setup_under_test", path_setup_file
+    )
+    assert specification is not None
+    assert specification.loader is not None
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+
+    assert hooks_root in sys.path
+    assert hooks_constants is not None