claude-dev-env 2.8.0 → 2.10.0

package/hooks/hooks_constants/piped_pytest_blocker_constants.py

@@ -13,7 +13,10 @@ flags from its first operand, the wrapper commands whose run passes through to
 the program behind them, the separator that rejoins a wrapper's argument
 tokens, the empty commenter set that leaves ``#`` to the comment-start pattern,
 the quote characters stripped before a basename read, and the deny message.
-Segment helpers come from ``shell_command_segments.py``.
+Segment helpers come from ``shell_command_segments.py``. Quote-aware pipeline
+parsing lives in ``shell_command_pipeline``. Pytest invocation classification
+that consumes these program, wrapper, and option constants lives in
+``pytest_invocation``.
 
 Two wrapper shapes reach the program behind them differently. ``sudo`` and
 ``uvx`` take their own option flags and then the command, so the step-over drops

package/hooks/hooks_constants/plain_language_blocker_constants.py

@@ -18,7 +18,9 @@ strippers the word scan runs first, and the lean-question-block tunables: the
 block-level chat-detail markers that belong in chat text, the line-ending
 spellings normalized before those markers run, the inline-code span the length
 counts collapse to one word, and the sentence and word caps a question and an
-option description each answer to.
+option description each answer to. The pure analyzer in
+``ask_user_question_shape`` reads the same lean-block tunables so shape grading
+and the runtime hook share one contract.
 """
 
 from __future__ import annotations
@@ -352,6 +354,7 @@ OPTION_DESCRIPTION_SURFACE_NAME: str = "an option description"
 
 LEAN_QUESTION_BLOCK_PREFIX: str = "BLOCKED: [LEAN_QUESTION] Question block carries chat detail -- "
 LEAN_QUESTION_VIOLATION_SEPARATOR: str = "; "
+HEAVY_WORD_SWAP_LIST_SEPARATOR: str = ", "
 LEAN_QUESTION_BLOCK_GUIDANCE: str = (
     "AskUserQuestion renders as one plain text block. Print the plan, the counts, "
     "and the tradeoffs in chat text before the call, keep the question block to a "

package/hooks/hooks_constants/pre_tool_use_dispatcher_constants.py

@@ -16,6 +16,8 @@ __all__ = [
     "BLOCKING_CRASH_EXIT_CODE",
     "EXIT_CODE_TWO_DENY_REASON",
     "BLOCKING_CRASH_DENY_REASON",
+    "REASON_JOIN_SEPARATOR",
+    "CONTEXT_JOIN_SEPARATOR",
     "WRITE_TOOL_NAME",
     "EDIT_TOOL_NAME",
     "MULTI_EDIT_TOOL_NAME",
@@ -23,6 +25,7 @@ __all__ = [
     "ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES",
     "STATE_DESCRIPTION_BLOCKER_MODULE_NAME",
     "PLAIN_LANGUAGE_BLOCKER_MODULE_NAME",
+    "SYSTEM_MESSAGE_JOIN_SEPARATOR",
     "HostedHookEntry",
     "ALL_HOSTED_HOOK_ENTRIES",
 ]
@@ -30,9 +33,12 @@ __all__ = [
 DENY_DECISION = "deny"
 ALLOW_DECISION = "allow"
 HOOK_EVENT_NAME = "PreToolUse"
+SYSTEM_MESSAGE_JOIN_SEPARATOR = "\n"
 BLOCKING_CRASH_EXIT_CODE = 2
 EXIT_CODE_TWO_DENY_REASON = "[dispatcher] hook denied via exit code 2 — write blocked"
 BLOCKING_CRASH_DENY_REASON = "[dispatcher] hook crash in blocking hook — write blocked for safety"
+REASON_JOIN_SEPARATOR = " | "
+CONTEXT_JOIN_SEPARATOR = "\n"
 
 WRITE_TOOL_NAME = "Write"
 EDIT_TOOL_NAME = "Edit"

package/hooks/hooks_constants/project_paths_reader.py

@@ -8,8 +8,11 @@ import os
 from pathlib import Path
 
 from hooks_constants.dynamic_stderr_handler import DynamicStderrHandler
-from hooks_constants.setup_project_paths_constants import META_KEY, UTF8_ENCODING
-
+from hooks_constants.setup_project_paths_constants import (
+    GIT_DIRECTORY_SEGMENT_NAME,
+    META_KEY,
+    UTF8_ENCODING,
+)
 
 _logger = logging.getLogger("project_paths_reader")
 if not _logger.handlers:
@@ -34,6 +37,30 @@ def _normalize_path_separators(raw_path: str) -> str:
     return os.path.normcase(os.path.normpath(forward_slash_form)).replace("\\", "/")
 
 
+def find_git_root(start_path: str) -> str | None:
+    """Walk upward for .git; stop at home or filesystem root.
+
+    Home bound prevents a parent .git above the user home from becoming the
+    session repo root (same contract as the untracked-repo SessionStart hook).
+
+    Args:
+        start_path: Directory to begin the upward walk.
+
+    Returns:
+        Absolute path of the git root, or None when none is found in bounds.
+    """
+    home_directory = Path.home().resolve()
+    candidate = Path(start_path).resolve()
+    while True:
+        if (candidate / GIT_DIRECTORY_SEGMENT_NAME).exists():
+            return str(candidate)
+        if candidate == home_directory:
+            return None
+        parent = candidate.parent
+        if parent == candidate:
+            return None
+        candidate = parent
+
 def load_registry(config_path: Path | None = None) -> dict[str, str]:
     """Return the name-to-absolute-path mapping with the _meta key stripped.
 
@@ -65,14 +92,14 @@ def load_registry(config_path: Path | None = None) -> dict[str, str]:
     }
 
 
-def registry_contains_path(known_registry: dict[str, str], path_to_find: str) -> bool:
+def registry_contains_path(all_known_registry: dict[str, str], path_to_find: str) -> bool:
     """Return True when the given path appears as any registry value.
 
     Normalizes both sides before comparing so Windows and POSIX separator
     forms of the same path compare equal.
     """
     normalized_target = _normalize_path_separators(path_to_find)
-    for each_registered_path in known_registry.values():
+    for each_registered_path in all_known_registry.values():
         if _normalize_path_separators(each_registered_path) == normalized_target:
             return True
     return False

package/hooks/hooks_constants/prose_matcher_precision_constants.py

@@ -0,0 +1,40 @@
+"""Thresholds and paths for prose-matcher precision measurement (OP-07B).
+
+::
+
+    labeled count < SAMPLE_FLOOR_PER_MATCHER  -> remain advisory
+    precision >= KEEP_PRECISION_FLOOR         -> keep
+    precision >= NARROW_PRECISION_FLOOR       -> narrow
+    otherwise                                 -> drop
+
+No matcher becomes hard-blocking from historical labels alone; classification
+only records keep/narrow/drop/advisory for the observation window.
+"""
+
+from __future__ import annotations
+
+ADVISORY_LOG_RELATIVE_PATH = ".claude/logs/prose-matcher-advisory.jsonl"
+SAMPLE_FLOOR_PER_MATCHER = 30
+KEEP_PRECISION_FLOOR = 0.7
+NARROW_PRECISION_FLOOR = 0.4
+MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD = "plain_language_heavy_word"
+MATCHER_ID_HEDGING_WORD = "hedging_word"
+ALL_KNOWN_MATCHER_IDS = (
+    MATCHER_ID_PLAIN_LANGUAGE_HEAVY_WORD,
+    MATCHER_ID_HEDGING_WORD,
+)
+DECISION_TRUE_POSITIVE = "true_positive"
+DECISION_FALSE_POSITIVE = "false_positive"
+DECISION_UNLABELED = "unlabeled"
+ALL_LABEL_DECISIONS = (
+    DECISION_TRUE_POSITIVE,
+    DECISION_FALSE_POSITIVE,
+    DECISION_UNLABELED,
+)
+CLASSIFICATION_KEEP = "keep"
+CLASSIFICATION_NARROW = "narrow"
+CLASSIFICATION_DROP = "drop"
+CLASSIFICATION_ADVISORY = "advisory"
+CONTEXT_FINGERPRINT_HEX_LENGTH = 16
+MAXIMUM_ADVISORY_EMITS_PER_CALL = 5
+ADVISORY_CONTEXT_SNIPPET_MAX_CHARS = 120

package/hooks/hooks_constants/pytest_invocation.py

@@ -0,0 +1,354 @@
+"""Classify whether a parsed simple-command segment runs pytest.
+
+Takes operator-stripped segment tokens and reports whether that segment invokes
+pytest — as a bare program, through a Python interpreter ``-m``, through a
+pass-through wrapper, or through a shell string-exec command.
+
+::
+
+    segment_runs_pytest(["pytest", "tests"])                 True
+    segment_runs_pytest(["python", "-m", "pytest"])          True
+    segment_runs_pytest(["uv", "run", "pytest", "tests"])    True
+    segment_runs_pytest(["python", "myscript.py", "-m", "pytest"])  False
+    segment_runs_pytest(["uv", "run", "--with", "pytest", "mypy", "."])  False
+
+Shell parsing (tokenization, heredoc drop, segment pairing) lives in
+``shell_command_pipeline``. Pipeline deny decisions stay with the blocker.
+This module only answers "does this segment run pytest?"
+"""
+
+from __future__ import annotations
+
+from hooks_constants.piped_pytest_blocker_constants import (
+    ALL_CLUSTERED_STRING_EXEC_OPTION_LETTERS,
+    ALL_FLAG_TAKING_WRAPPER_COMMANDS,
+    ALL_PYTEST_PROGRAM_BASENAMES,
+    ALL_QUOTE_CHARACTERS,
+    ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS,
+    ALL_SHORT_OPTION_CLUSTERING_SHELL_BASENAMES,
+    ALL_STRING_EXEC_COMMAND_FLAGS,
+    ALL_STRING_EXECUTING_SHELL_BASENAMES,
+    ALL_VALUE_TAKING_INTERPRETER_OPTION_FLAGS,
+    ALL_VALUE_TAKING_SHELL_OPTION_FLAGS,
+    ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS,
+    COMMAND_OPTION_TOKEN_PATTERN,
+    END_OF_OPTIONS_TOKEN,
+    MODULE_RUN_FLAG,
+    PYTEST_MODULE_NAME,
+    PYTHON_INTERPRETER_BASENAME_PATTERN,
+    RUN_SUBCOMMAND_NAME,
+    SHORT_OPTION_CLUSTER_PATTERN,
+    SHORT_OPTION_PREFIX,
+    TOOL_SUBCOMMAND_NAME,
+    WRAPPED_COMMAND_TOKEN_JOIN,
+)
+from hooks_constants.shell_command_pipeline import (
+    all_operator_aware_tokenizations,
+    segments_with_following_operator,
+)
+from hooks_constants.shell_command_segments import (
+    effective_leading_program,
+    token_basename,
+)
+
+__all__ = [
+    "segment_reports_a_pytest_exit_code",
+    "segment_runs_pytest",
+    "string_exec_inner_command",
+    "unquoted_token",
+]
+
+
+def unquoted_token(token: str) -> str:
+    """Return a token with its surrounding shell quotes removed.
+
+    Args:
+        token: One shell token, possibly quoted.
+
+    Returns:
+        The same token with leading and trailing quote characters stripped.
+    """
+    return token.strip(ALL_QUOTE_CHARACTERS)
+
+
+def _glued_module_name(token: str) -> str | None:
+    """Return the module name glued onto a ``-m`` flag, or None for any other token.
+
+    ::
+
+        -mpytest   pytest
+        -mmypy     mypy
+        -m         None
+    """
+    stripped_token = unquoted_token(token)
+    if not stripped_token.startswith(MODULE_RUN_FLAG):
+        return None
+    return stripped_token[len(MODULE_RUN_FLAG) :] or None
+
+
+def _some_module_run_flag_names_pytest(all_tokens: list[str]) -> bool:
+    """Return True when any ``-m`` among the tokens names pytest."""
+    for each_index, each_token in enumerate(all_tokens):
+        if _glued_module_name(each_token) == PYTEST_MODULE_NAME:
+            return True
+        if each_token != MODULE_RUN_FLAG:
+            continue
+        module_index = each_index + 1
+        if module_index >= len(all_tokens):
+            continue
+        if unquoted_token(all_tokens[module_index]) == PYTEST_MODULE_NAME:
+            return True
+    return False
+
+
+def _clustered_option_value_token_count(
+    stripped_token: str, all_value_taking_flags: frozenset[str]
+) -> int:
+    """Return how many tokens a short-option cluster takes as its last flag value."""
+    all_cluster_letters = stripped_token[len(SHORT_OPTION_PREFIX) :]
+    last_letter_position = len(all_cluster_letters) - 1
+    for each_position, each_letter in enumerate(all_cluster_letters):
+        if SHORT_OPTION_PREFIX + each_letter not in all_value_taking_flags:
+            continue
+        return int(each_position == last_letter_position)
+    return 0
+
+
+def _option_value_token_count(
+    stripped_token: str, all_value_taking_flags: frozenset[str]
+) -> int:
+    """Return how many tokens after an option token are that option's value."""
+    if stripped_token in all_value_taking_flags:
+        return 1
+    if SHORT_OPTION_CLUSTER_PATTERN.fullmatch(stripped_token) is None:
+        return 0
+    return _clustered_option_value_token_count(stripped_token, all_value_taking_flags)
+
+
+def _all_tokens_from_the_interpreter_module_flag(
+    all_interpreter_argument_tokens: list[str],
+) -> list[str] | None:
+    """Return tokens from the interpreter's own ``-m`` on, or None when it has none."""
+    scan_index = 0
+    while scan_index < len(all_interpreter_argument_tokens):
+        each_token = all_interpreter_argument_tokens[scan_index]
+        stripped_token = unquoted_token(each_token)
+        if stripped_token == MODULE_RUN_FLAG or _glued_module_name(each_token) is not None:
+            return all_interpreter_argument_tokens[scan_index:]
+        if COMMAND_OPTION_TOKEN_PATTERN.match(stripped_token) is None:
+            return None
+        scan_index += 1 + _option_value_token_count(
+            stripped_token, ALL_VALUE_TAKING_INTERPRETER_OPTION_FLAGS
+        )
+    return None
+
+
+def _runs_pytest_as_a_module(all_interpreter_argument_tokens: list[str]) -> bool:
+    """Return True when the interpreter's own ``-m`` reaches a pytest run."""
+    all_module_tokens = _all_tokens_from_the_interpreter_module_flag(
+        all_interpreter_argument_tokens
+    )
+    if all_module_tokens is None:
+        return False
+    return _some_module_run_flag_names_pytest(all_module_tokens)
+
+
+def _all_tokens_from_the_first_operand(all_tokens: list[str]) -> list[str]:
+    """Return the tokens from the first non-option one on, dropping option flags."""
+    all_remaining_tokens = all_tokens
+    while all_remaining_tokens:
+        stripped_token = unquoted_token(all_remaining_tokens[0])
+        if stripped_token == END_OF_OPTIONS_TOKEN:
+            return all_remaining_tokens[1:]
+        if COMMAND_OPTION_TOKEN_PATTERN.match(stripped_token) is None:
+            return all_remaining_tokens
+        flag_value_token_count = _option_value_token_count(
+            stripped_token, ALL_VALUE_TAKING_WRAPPER_OPTION_FLAGS
+        )
+        all_remaining_tokens = all_remaining_tokens[1 + flag_value_token_count :]
+    return []
+
+
+def _all_tokens_after_one_wrapper(all_segment_tokens: list[str]) -> list[str] | None:
+    """Return the tokens a single leading pass-through wrapper runs, else None."""
+    leading_program = effective_leading_program(all_segment_tokens)
+    if leading_program is None:
+        return None
+    program_basename = token_basename(unquoted_token(leading_program))
+    leading_index = all_segment_tokens.index(leading_program)
+    all_argument_tokens = _all_tokens_from_the_first_operand(
+        all_segment_tokens[leading_index + 1 :]
+    )
+    if program_basename in ALL_FLAG_TAKING_WRAPPER_COMMANDS:
+        return all_argument_tokens
+    if program_basename not in ALL_RUN_SUBCOMMAND_WRAPPER_COMMANDS:
+        return None
+    if all_argument_tokens and unquoted_token(all_argument_tokens[0]) == TOOL_SUBCOMMAND_NAME:
+        all_argument_tokens = _all_tokens_from_the_first_operand(all_argument_tokens[1:])
+    if not all_argument_tokens or unquoted_token(all_argument_tokens[0]) != RUN_SUBCOMMAND_NAME:
+        return None
+    return _all_tokens_from_the_first_operand(all_argument_tokens[1:])
+
+
+def _all_tokens_after_wrappers(all_segment_tokens: list[str]) -> list[str]:
+    """Return the segment tokens with every leading pass-through wrapper stepped over."""
+    all_remaining_tokens = all_segment_tokens
+    while True:
+        all_stepped_tokens = _all_tokens_after_one_wrapper(all_remaining_tokens)
+        if all_stepped_tokens is None:
+            return all_remaining_tokens
+        all_remaining_tokens = all_stepped_tokens
+
+
+def segment_runs_pytest(all_segment_tokens: list[str]) -> bool:
+    """Return True when a simple-command segment invokes pytest.
+
+    ::
+
+        ['pytest', 'tests']                         True
+        ['python', '-m', 'pytest']                  True
+        ['python', '-mpytest']                      True
+        ['time', 'pytest', 'tests']                 True
+        ['sudo', 'pytest', 'tests']                 True
+        ['uv', 'run', 'pytest', 'tests']            True
+        ['C:\\\\Python313\\\\python.exe', '-m', 'pytest']  True
+        ['python', '-m', 'mypy']                    False
+        ['git', 'status']                           False
+        ['python', 'myscript.py', '-m', 'pytest']   False
+        ['uv', 'run', '--with', 'pytest', 'mypy']   False
+        []                                          False
+
+    Args:
+        all_segment_tokens: Tokens of one simple command, operators removed.
+
+    Returns:
+        True when the segment's program is pytest or a Python interpreter
+        running the pytest module, including through pass-through wrappers.
+    """
+    all_unwrapped_tokens = _all_tokens_after_wrappers(all_segment_tokens)
+    leading_program = effective_leading_program(all_unwrapped_tokens)
+    if leading_program is None:
+        return False
+    program_basename = token_basename(unquoted_token(leading_program))
+    if program_basename in ALL_PYTEST_PROGRAM_BASENAMES:
+        return True
+    if not PYTHON_INTERPRETER_BASENAME_PATTERN.fullmatch(program_basename):
+        return False
+    interpreter_index = all_unwrapped_tokens.index(leading_program)
+    return _runs_pytest_as_a_module(all_unwrapped_tokens[interpreter_index + 1 :])
+
+
+def _clustered_string_exec_flag_offset(stripped_token: str) -> int | None:
+    """Return how far past a cluster its command string sits, or None when absent."""
+    if SHORT_OPTION_CLUSTER_PATTERN.fullmatch(stripped_token) is None:
+        return None
+    all_cluster_letters = stripped_token[len(SHORT_OPTION_PREFIX) :]
+    if not any(
+        each_letter in ALL_CLUSTERED_STRING_EXEC_OPTION_LETTERS
+        for each_letter in all_cluster_letters
+    ):
+        return None
+    return sum(
+        SHORT_OPTION_PREFIX + each_letter.lower() in ALL_VALUE_TAKING_SHELL_OPTION_FLAGS
+        for each_letter in all_cluster_letters
+    )
+
+
+def _string_exec_flag_index(
+    all_argument_tokens: list[str], *, clusters_short_options: bool
+) -> int | None:
+    """Return the index of a wrapper's string-exec flag, or None when it takes none."""
+    scan_index = 0
+    while scan_index < len(all_argument_tokens):
+        stripped_token = unquoted_token(all_argument_tokens[scan_index])
+        lowercased_token = stripped_token.lower()
+        if lowercased_token == END_OF_OPTIONS_TOKEN:
+            return None
+        if lowercased_token in ALL_STRING_EXEC_COMMAND_FLAGS:
+            return scan_index
+        if clusters_short_options:
+            clustered_flag_offset = _clustered_string_exec_flag_offset(stripped_token)
+            if clustered_flag_offset is not None:
+                return scan_index + clustered_flag_offset
+        if COMMAND_OPTION_TOKEN_PATTERN.match(lowercased_token) is None:
+            return None
+        scan_index += 1 + _option_value_token_count(
+            lowercased_token, ALL_VALUE_TAKING_SHELL_OPTION_FLAGS
+        )
+    return None
+
+
+def string_exec_inner_command(all_segment_tokens: list[str]) -> str | None:
+    """Return the command string a shell wrapper runs, or None for any other segment.
+
+    ::
+
+        bash -c 'pytest | tee run.log'         pytest | tee run.log
+        bash -euc 'pytest | tee run.log'       pytest | tee run.log
+        pwsh -Command 'pytest'                 pytest
+        cmd /c python -m pytest tests          python -m pytest tests
+        bash scripts/ci.sh -c 'pytest tests'   None
+        pytest tests                           None
+
+    Args:
+        all_segment_tokens: Tokens of one simple command, operators removed.
+
+    Returns:
+        The inner command string the shell executes, or None when the segment
+        is not a string-executing shell wrapper with a command string.
+    """
+    all_unwrapped_tokens = _all_tokens_after_wrappers(all_segment_tokens)
+    leading_program = effective_leading_program(all_unwrapped_tokens)
+    if leading_program is None:
+        return None
+    shell_basename = token_basename(unquoted_token(leading_program))
+    if shell_basename not in ALL_STRING_EXECUTING_SHELL_BASENAMES:
+        return None
+    leading_index = all_unwrapped_tokens.index(leading_program)
+    all_argument_tokens = all_unwrapped_tokens[leading_index + 1 :]
+    flag_index = _string_exec_flag_index(
+        all_argument_tokens,
+        clusters_short_options=shell_basename in ALL_SHORT_OPTION_CLUSTERING_SHELL_BASENAMES,
+    )
+    if flag_index is None:
+        return None
+    inner_index = flag_index + 1
+    if inner_index >= len(all_argument_tokens):
+        return None
+    return WRAPPED_COMMAND_TOKEN_JOIN.join(all_argument_tokens[inner_index:])
+
+
+def _wrapped_command_runs_pytest(inner_command: str) -> bool:
+    """Return True when the command string a shell wrapper runs invokes pytest."""
+    for each_tokenization in all_operator_aware_tokenizations(inner_command):
+        for each_segment, _each_operator in segments_with_following_operator(
+            each_tokenization
+        ):
+            if segment_runs_pytest(each_segment):
+                return True
+    return False
+
+
+def segment_reports_a_pytest_exit_code(all_segment_tokens: list[str]) -> bool:
+    """Return True when the segment's exit code is pytest's, directly or via a wrapper.
+
+    ::
+
+        ['pytest', 'tests']                  True
+        ['bash', '-c', 'pytest tests']       True
+        ['bash', 'script.sh']                False
+        ['python', '-m', 'pytest']           True
+
+    Args:
+        all_segment_tokens: Tokens of one simple command, operators removed.
+
+    Returns:
+        True when the segment runs pytest, or a shell wrapper whose command
+        string runs pytest (so the shell exits with pytest's code).
+    """
+    if segment_runs_pytest(all_segment_tokens):
+        return True
+    inner_command = string_exec_inner_command(all_segment_tokens)
+    if inner_command is None:
+        return False
+    return _wrapped_command_runs_pytest(inner_command)

package/hooks/hooks_constants/session_start_injector.py

@@ -0,0 +1,163 @@
+"""Shared SessionStart context injector for starter hooks.
+
+Pure decision helper: normalize the SessionStart ``source``, honor enable and
+timeout configuration, and return a structured result every caller can emit as
+``additionalContext`` or ignore.
+
+::
+
+    inject({"source": "startup"}, config)  -> status ok + context for startup
+    inject({"source": "resume"}, disabled) -> status disabled, no context
+    inject({"source": "weird"}, config)    -> status unknown_source
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from hooks_constants.session_start_injector_constants import (
+    ALL_DEFAULT_CONTEXT_BY_SOURCE,
+    ALL_INJECTOR_ENABLED_ENV_VALUES,
+    ALL_KNOWN_SESSION_START_SOURCES,
+    DEFAULT_INJECTOR_TIMEOUT_MILLISECONDS,
+    INJECTION_STATUS_DISABLED,
+    INJECTION_STATUS_OK,
+    INJECTION_STATUS_TIMEOUT,
+    INJECTION_STATUS_UNKNOWN_SOURCE,
+    MILLISECONDS_PER_SECOND,
+    SESSION_START_INJECTOR_ENABLED_ENV_VAR,
+    SESSION_START_SOURCE_PAYLOAD_KEY,
+    SESSION_START_SOURCE_UNKNOWN,
+)
+
+
+@dataclass(frozen=True)
+class InjectorConfiguration:
+    """Runtime knobs for one SessionStart injection.
+
+    Attributes:
+        is_enabled: When False, inject returns quickly with status disabled.
+        timeout_milliseconds: Budget; at or below zero yields status timeout.
+        context_by_source: Map of known source -> additionalContext text.
+        default_context_for_unknown: Context when source is not a known value.
+    """
+
+    is_enabled: bool
+    timeout_milliseconds: int
+    context_by_source: Mapping[str, str]
+    default_context_for_unknown: str = ""
+
+
+@dataclass(frozen=True)
+class InjectionResult:
+    """Structured outcome of one inject call.
+
+    Attributes:
+        source: Normalized SessionStart source (or ``unknown``).
+        status: One of the INJECTION_STATUS_* constants.
+        additional_context: Text to emit, empty when not injected.
+        latency_milliseconds: Wall time for this inject call.
+        is_context_injected: True when additional_context is non-empty.
+    """
+
+    source: str
+    status: str
+    additional_context: str
+    latency_milliseconds: float
+    is_context_injected: bool
+
+
+def injector_enabled_in_environment() -> bool:
+    """Return whether the injector is enabled from the environment.
+
+    Unset or empty means enabled (default on). Explicit falsey values disable.
+    """
+    raw_setting = os.environ.get(SESSION_START_INJECTOR_ENABLED_ENV_VAR)
+    if raw_setting is None or raw_setting.strip() == "":
+        return True
+    return raw_setting.strip().lower() in ALL_INJECTOR_ENABLED_ENV_VALUES
+
+
+def default_injector_configuration() -> InjectorConfiguration:
+    """Build the default configuration from environment and constants."""
+    return InjectorConfiguration(
+        is_enabled=injector_enabled_in_environment(),
+        timeout_milliseconds=DEFAULT_INJECTOR_TIMEOUT_MILLISECONDS,
+        context_by_source=dict(ALL_DEFAULT_CONTEXT_BY_SOURCE),
+        default_context_for_unknown="",
+    )
+
+
+def normalize_session_start_source(payload_by_key: Mapping[str, object]) -> str:
+    """Return the SessionStart source string, or unknown when missing/invalid."""
+    raw_source = payload_by_key.get(SESSION_START_SOURCE_PAYLOAD_KEY, "")
+    if not isinstance(raw_source, str):
+        return SESSION_START_SOURCE_UNKNOWN
+    normalized_source = raw_source.strip().lower()
+    if not normalized_source:
+        return SESSION_START_SOURCE_UNKNOWN
+    if normalized_source not in ALL_KNOWN_SESSION_START_SOURCES:
+        return SESSION_START_SOURCE_UNKNOWN
+    return normalized_source
+
+
+def inject_session_start_context(
+    payload_by_key: Mapping[str, object],
+    configuration: InjectorConfiguration,
+    *,
+    clock: Callable[[], float] | None = None,
+) -> InjectionResult:
+    """Decide SessionStart context for one payload under the given configuration.
+
+    Args:
+        payload_by_key: Parsed SessionStart stdin payload.
+        configuration: Enable flag, timeout budget, and per-source context.
+        clock: Optional monotonic clock for latency (tests inject a stub).
+
+    Returns:
+        An InjectionResult with status, source, context, and latency.
+    """
+    read_clock = clock if clock is not None else time.perf_counter
+    start_time = read_clock()
+    normalized_source = normalize_session_start_source(payload_by_key)
+
+    if not configuration.is_enabled:
+        status = INJECTION_STATUS_DISABLED
+        context_text = ""
+    elif configuration.timeout_milliseconds <= 0:
+        status = INJECTION_STATUS_TIMEOUT
+        context_text = ""
+    elif normalized_source == SESSION_START_SOURCE_UNKNOWN:
+        status = INJECTION_STATUS_UNKNOWN_SOURCE
+        context_text = configuration.default_context_for_unknown
+    else:
+        status = INJECTION_STATUS_OK
+        context_text = configuration.context_by_source.get(normalized_source, "")
+
+    end_time = read_clock()
+    return InjectionResult(
+        source=normalized_source,
+        status=status,
+        additional_context=context_text,
+        latency_milliseconds=(end_time - start_time)
+        * MILLISECONDS_PER_SECOND,
+        is_context_injected=bool(context_text),
+    )
+
+
+def build_additional_context_payload(injection_result: InjectionResult) -> dict[str, str]:
+    """Return the SessionStart stdout object when context was injected.
+
+    Args:
+        injection_result: Result from inject_session_start_context.
+
+    Returns:
+        ``{"additionalContext": ...}`` when injected, else empty dict.
+    """
+    if not injection_result.is_context_injected:
+        return {}
+    return {"additionalContext": injection_result.additional_context}
+