claude-dev-env 7.5.0 → 7.6.0

package/hooks/blocking/code_rules_comments.py

@@ -30,6 +30,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES,
     CHAINED_INLINE_COMMENT_PATTERN,
     MAX_COMMENT_ISSUES,
+    STEALTH_KEEP_COMMENT_MARKER,
 )
 _javascript_comment_scanner = importlib.import_module("javascript_comment_scanner")
 extract_javascript_comment_occurrences = (
@@ -152,10 +153,36 @@ def _python_comment_occurrences(
     return all_occurrences, True
 
 
+def _is_stealth_keep_occurrence(comment_text: str) -> bool:
+    """Return True for a ``# STEALTH: Keep`` occurrence.
+
+    ``STEALTH: Keep`` is meant to be freely added and to survive edits to
+    the line it sits on, unlike ``noqa`` or ``TODO``, which AGENTS.md
+    requires to be removed rather than added or justified. It is excluded
+    here rather than through the shared exempt-marker set that
+    ``check_comment_changes`` deliberately still blocks on add.
+    """
+    return comment_text.startswith("#") and comment_text[1:].lstrip().startswith(
+        STEALTH_KEEP_COMMENT_MARKER
+    )
+
+
+def _without_stealth_keep_occurrences(
+    all_occurrences: list[tuple[str, int, bool]]
+) -> list[tuple[str, int, bool]]:
+    return [
+        each_occurrence
+        for each_occurrence in all_occurrences
+        if not _is_stealth_keep_occurrence(each_occurrence[0])
+    ]
+
+
 def check_comment_changes(old_content: str, new_content: str, file_path: str) -> list[str]:
     """Check for comment additions or removals between old and new content.
 
-    Inline and standalone comments are blocking findings when added.
+    Inline and standalone comments are blocking findings when added, except
+    ``STEALTH: Keep`` occurrences, which are excluded entirely so the marker
+    can be added and can persist across edits to its line.
     Existing comments can be removed when the touched code no longer needs them.
 
     When the file is Python and either *old_content* or *new_content* cannot
@@ -178,6 +205,9 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
         old_occurrences = extract_javascript_comment_occurrences(old_content, True)
         new_occurrences = extract_javascript_comment_occurrences(new_content, True)
 
+    old_occurrences = _without_stealth_keep_occurrences(old_occurrences)
+    new_occurrences = _without_stealth_keep_occurrences(new_occurrences)
+
     old_occurrence_counts = Counter(
         (each_text, is_inline)
         for each_text, _line_number, is_inline in old_occurrences
@@ -264,6 +294,8 @@ def _retained_comment_issues(
     (old_occurrences, old_tokenize_ok), (new_occurrences, new_tokenize_ok) = (_comment_occurrences(old_content, file_path, True), _comment_occurrences(new_content, file_path, True))
     if not (old_tokenize_ok and new_tokenize_ok):
         return []
+    old_occurrences = _without_stealth_keep_occurrences(old_occurrences)
+    new_occurrences = _without_stealth_keep_occurrences(new_occurrences)
     all_changed_lines, all_deleted_lines, old_line_by_new_line = _line_diff_data(old_content, new_content)
     old_line_by_key = {
         each_key: [each_line for each_text, each_line, each_is_inline in old_occurrences if (each_text, each_is_inline) == each_key]
@@ -346,12 +378,14 @@ def _is_exempt_python_comment(comment_token: tokenize.TokenInfo) -> bool:
     token-anchored directive body never legitimately carries a ``#``
     (noqa codes, pylint symbols, and pragma directives contain none), so
     any inner ``#`` reliably marks chained prose. Free-form markers
-    (``type:``, ``TODO``, ``FIXME``, ``HACK``, ``XXX``) accept any
-    trailing prose:
+    (``type:``, ``TODO``, ``FIXME``, ``HACK``, ``XXX``, ``STEALTH: Keep``)
+    accept any trailing prose:
     ``# type:`` participates in the documented justification
     convention enforced by ``check_type_escape_hatches`` (which
-    requires a trailing reason), and the TODO-family markers carry
-    annotation text by convention.
+    requires a trailing reason), the TODO-family markers carry
+    annotation text by convention, and ``STEALTH: Keep`` is the
+    acknowledged-bypass marker the CDP runtime-usage scanner reads
+    from the flagged line together with its reason.
     """
     comment_string = comment_token.string
     if comment_string.startswith("#!") and comment_token.start == (1, 0):

package/hooks/blocking/pii_prevention_blocker_parts/repository_exemption.py

@@ -16,6 +16,8 @@ import sys
 from pathlib import Path
 from urllib.parse import urlparse
 
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+
 try:
     _blocking_directory = str(Path(__file__).resolve().parent.parent)
     _hooks_directory = str(Path(__file__).resolve().parent.parent.parent)
@@ -186,6 +188,7 @@ def _repository_origin_slug(repository_root: Path) -> str | None:
             text=True,
             timeout=GIT_COMMAND_TIMEOUT_SECONDS,
             cwd=str(repository_root),
+            creationflags=hidden_window_creation_flags(),
         )
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
         return None

package/hooks/blocking/precommit_code_rules_gate.py

@@ -18,6 +18,8 @@ from hooks_constants.precommit_code_rules_gate_constants import (  # noqa: E402
     GIT_COMMAND_TIMEOUT_SECONDS,
 )
 
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+
 
 def resolve_repository_root(working_directory: str | None) -> Path | None:
     """Resolve the Git repository root for a directory.
@@ -36,6 +38,7 @@ def resolve_repository_root(working_directory: str | None) -> Path | None:
             text=True,
             timeout=GIT_COMMAND_TIMEOUT_SECONDS,
             cwd=working_directory,
+            creationflags=hidden_window_creation_flags(),
         )
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
         return None

package/hooks/blocking/tdd_enforcer_parts/content_analysis.py

@@ -30,6 +30,10 @@ def _safe_constant_attribute_calls() -> frozenset[tuple[str, str]]:
     return frozenset({("re", "compile")})
 
 
+def _safe_string_literal_methods() -> frozenset[str]:
+    return frozenset({"join"})
+
+
 def _node_is_unsafe_construct(subnode: ast.AST) -> bool:
     return isinstance(
         subnode,
@@ -37,7 +41,18 @@ def _node_is_unsafe_construct(subnode: ast.AST) -> bool:
     )
 
 
+def _is_safe_string_literal_method_call(function_node: ast.Attribute) -> bool:
+    receiver = function_node.value
+    return (
+        isinstance(receiver, ast.Constant)
+        and isinstance(receiver.value, str)
+        and function_node.attr in _safe_string_literal_methods()
+    )
+
+
 def _attribute_call_is_unsafe(function_node: ast.Attribute) -> bool:
+    if _is_safe_string_literal_method_call(function_node):
+        return False
     if not isinstance(function_node.value, ast.Name):
         return True
     pair = (function_node.value.id, function_node.attr)
@@ -56,9 +71,10 @@ def _call_is_unsafe(call_node: ast.Call) -> bool:
 def _rhs_has_unsafe_call(rhs_node: ast.AST) -> bool:
     """Return True when a constant's value contains a non-allowlisted call.
 
-    Safe calls are value constructors (``Path(...)``, ``re.compile(...)``) that
-    build objects without side effects; any other call or a comprehension reads
-    as import-time behavior.
+    Safe calls are value constructors (``Path(...)``, ``re.compile(...)``) and
+    a pure string-literal method call (``"|".join(...)``) that build objects
+    without side effects; any other call or a comprehension reads as
+    import-time behavior.
 
     Args:
         rhs_node: The assignment's right-hand-side expression node.

package/hooks/blocking/tdd_enforcer_parts/git_tracking.py

@@ -29,6 +29,8 @@ from tdd_enforcer_parts.config.tdd_enforcer_constants import (
     GIT_PATHSPEC_SEPARATOR,
 )
 
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+
 
 def _git_ls_files_command(file_name: str) -> list[str]:
     return [GIT_EXECUTABLE_NAME, GIT_LS_FILES_SUBCOMMAND, GIT_PATHSPEC_SEPARATOR, file_name]
@@ -57,6 +59,7 @@ def _git_tracks_path(path: Path) -> bool:
             text=True,
             check=False,
             timeout=GIT_LS_FILES_TIMEOUT_SECONDS,
+            creationflags=hidden_window_creation_flags(),
         )
     except (OSError, subprocess.SubprocessError):
         return False
@@ -80,6 +83,7 @@ def _working_tree_differs_from_head(path: Path) -> bool:
             text=True,
             check=False,
             timeout=GIT_DIFF_TIMEOUT_SECONDS,
+            creationflags=hidden_window_creation_flags(),
         )
     except (OSError, subprocess.SubprocessError):
         return True

package/hooks/blocking/tdd_enforcer_parts/tests/test_content_analysis.py

@@ -12,6 +12,31 @@ def test_constants_only_rejects_function_definition() -> None:
     assert content_analysis._is_constants_only_python_content("def f():\n    return 1\n") is False
 
 
+def test_constants_only_accepts_join_on_a_string_literal_inside_re_compile() -> None:
+    content = (
+        '"""doc."""\n'
+        "import re\n"
+        "NAMES = ('one', 'two')\n"
+        'PATTERN = re.compile("(" + "|".join(NAMES) + ")")\n'
+    )
+    assert content_analysis._is_constants_only_python_content(content) is True
+
+
+def test_constants_only_rejects_join_on_a_non_literal_receiver() -> None:
+    content = (
+        '"""doc."""\n'
+        'SEPARATOR = "|"\n'
+        'NAMES = ("one", "two")\n'
+        "PATTERN = SEPARATOR.join(NAMES)\n"
+    )
+    assert content_analysis._is_constants_only_python_content(content) is False
+
+
+def test_constants_only_rejects_a_non_allowlisted_method_on_a_string_literal() -> None:
+    content = '"""doc."""\nSHOUT = "hi".upper()\n'
+    assert content_analysis._is_constants_only_python_content(content) is False
+
+
 def test_post_edit_import_only_allows_import_removal() -> None:
     existing = "import os\n\ndef run(): return 1\n"
     tool_input = {"old_string": "import os\n", "new_string": ""}

package/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py

@@ -133,6 +133,33 @@ def test_check_comment_changes_allows_comment_removal_without_advisory(
     assert captured.err == ""
 
 
+def test_check_comment_changes_does_not_flag_added_stealth_keep_marker() -> None:
+    old_content = "x = 1\n"
+    new_content = "x = 1  # STEALTH: Keep -- reason\n"
+    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
+    assert issues == []
+
+
+def test_check_comment_changes_does_not_flag_stealth_keep_retained_on_touched_line() -> None:
+    old_content = "x = 1  # STEALTH: Keep -- reason\n"
+    new_content = "x = 2  # STEALTH: Keep -- reason\n"
+    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
+    assert issues == []
+
+
+@pytest.mark.parametrize(
+    "each_marker",
+    ("# noqa: E501", "# type: ignore[misc]", "# TODO: revisit", "# FIXME: revisit"),
+)
+def test_check_comment_changes_still_flags_other_added_directive_markers(
+    each_marker: str,
+) -> None:
+    old_content = "x = 1\n"
+    new_content = f"x = 1  {each_marker}\n"
+    issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "foo.py")
+    assert any("comment added" in each_issue.lower() for each_issue in issues)
+
+
 def test_python_check_should_exempt_directive_without_space_after_hash() -> None:
     for each_directive in ("#noqa", "#type: ignore", "#pylint: disable", "#pragma: no cover"):
         content = f"{each_directive}\n"

package/hooks/blocking/test_code_rules_enforcer_exempt_marker_chained.py

@@ -156,6 +156,16 @@ def test_should_exempt_fixme_with_trailing_prose() -> None:
     assert _is_exempt_python_comment(token) is True
 
 
+def test_should_exempt_stealth_keep_with_trailing_reason() -> None:
+    token = _build_comment_token("# STEALTH: Keep bypass reviewed in incident 4021")
+    assert _is_exempt_python_comment(token) is True
+
+
+def test_should_flag_stealth_marker_missing_required_space_after_colon() -> None:
+    token = _build_comment_token("# STEALTH:Keep bypass reviewed in incident 4021")
+    assert _is_exempt_python_comment(token) is False
+
+
 def test_should_exempt_shebang_at_line_one_column_zero() -> None:
     token = tokenize.TokenInfo(
         type=tokenize.COMMENT,

package/hooks/git-hooks/git_hooks_constants/verification_notice_constants.py

@@ -111,6 +111,4 @@ ALL_RUNNER_FIELDS: frozenset[str] = frozenset(
 )
 AUTOMATIC_ADVISORY_DIRECTORY_NAME: str = "automatic_advisory"
 AUTOMATIC_ADVISORY_CLI_FILE_NAME: str = "cli.py"
-WINDOWS_PLATFORM: str = "win32"
-CREATE_NO_WINDOW_ATTRIBUTE: str = "CREATE_NO_WINDOW"
 POWERSHELL_CALL_OPERATOR: str = "& "

package/hooks/git-hooks/pull_request_handoff.py

@@ -9,6 +9,8 @@ from git_hooks_constants import (
     GH_PR_VIEW_TIMEOUT_SECONDS,
 )
 
+from subprocess_window_access import hidden_window_creation_flags
+
 
 def get_pull_request_url(repo_dir: Path) -> str | None:
     try:
@@ -19,6 +21,7 @@ def get_pull_request_url(repo_dir: Path) -> str | None:
             capture_output=True,
             text=True,
             timeout=GH_PR_VIEW_TIMEOUT_SECONDS,
+            creationflags=hidden_window_creation_flags(),
         )
     except (OSError, subprocess.SubprocessError):
         return None

package/hooks/git-hooks/subprocess_window_access.py

@@ -0,0 +1,41 @@
+"""Reach the hidden-window helpers from the scripts this directory deploys.
+
+The installer copies this directory into a profile that holds no installed
+Python distribution, and this repository's own tests run the deployed scripts
+under ``python -S -E``, which hides every installed package from the child
+process. On both routes ``hooks_constants`` is reachable only through the
+deployed ``hooks`` directory, so this module puts that directory on
+``sys.path`` and re-exports the helpers a caller asks for::
+
+    from subprocess_window_access import hidden_window_creation_flags
+
+The directory goes on the end of ``sys.path``. ``PathFinder`` runs ahead of
+every editable-install finder, so a trailing entry still selects the deployed
+copy, and the head of ``sys.path`` stays exactly as the caller left it. A
+caller that prepended its own roots keeps them first.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_subprocess_window_hooks_directory = str(
+    Path(__file__).resolve().parents[2] / "hooks"
+)
+if _subprocess_window_hooks_directory not in sys.path:
+    sys.path.append(_subprocess_window_hooks_directory)
+
+from hooks_constants.subprocess_window import (
+    HiddenWindowStartupInfo,
+    detached_hidden_window_creation_flags,
+    hidden_window_creation_flags,
+    inherited_stream_startup_info,
+)
+
+__all__ = [
+    "HiddenWindowStartupInfo",
+    "detached_hidden_window_creation_flags",
+    "hidden_window_creation_flags",
+    "inherited_stream_startup_info",
+]

package/hooks/git-hooks/test_verification_start.py

@@ -15,6 +15,9 @@ from verification_notice import build_verification_notice
 from verification_notice_context import VerificationNoticeContext
 from verification_start import start_automatic_advisory
 
+WINDOWS_NO_WINDOW_FLAG = 0x08000000
+EXPECTED_HIDDEN_WINDOW_FLAGS = WINDOWS_NO_WINDOW_FLAG if sys.platform == "win32" else 0
+
 
 def build_context(
     repository_root: Path,
@@ -102,6 +105,7 @@ def _assert_launch_matches_runner(
     assert launch_options["stdin"] is subprocess.DEVNULL
     assert launch_options["stdout"] is subprocess.DEVNULL
     assert launch_options["stderr"] is subprocess.DEVNULL
+    assert launch_options["creationflags"] == EXPECTED_HIDDEN_WINDOW_FLAGS
     assert "--once" not in command
 
 

package/hooks/git-hooks/verification_notice_context.py

@@ -36,6 +36,8 @@ from git_hooks_constants.verification_notice_constants import (
 )
 from local_verification.manifest import ManifestRunFatal, load_manifest
 
+from subprocess_window_access import hidden_window_creation_flags
+
 
 @dataclass(frozen=True)
 class VerificationNoticeContext:
@@ -202,6 +204,7 @@ def _run_git_query(
             encoding=GIT_OUTPUT_ENCODING_NAME,
             errors=GIT_OUTPUT_DECODE_ERRORS_POLICY,
             timeout=GIT_COMMAND_TIMEOUT_SECONDS,
+            creationflags=hidden_window_creation_flags(),
         )
     except (OSError, subprocess.SubprocessError, UnicodeError):
         return None

package/hooks/git-hooks/verification_start.py

@@ -13,7 +13,6 @@ from git_hooks_constants.verification_notice_constants import (
     ALL_RUNNER_FIELDS,
     AUTOMATIC_ADVISORY_CLI_FILE_NAME,
     AUTOMATIC_ADVISORY_DIRECTORY_NAME,
-    CREATE_NO_WINDOW_ATTRIBUTE,
     EXECUTOR_DIRECTORY_NAME,
     GIT_DIRECTORY_NAME,
     JSON_ENCODING,
@@ -22,10 +21,15 @@ from git_hooks_constants.verification_notice_constants import (
     RUNNER_PYTHON_FIELD,
     RUNNER_SETTINGS_FIELD,
     TARGET_REPOSITORY_REMOTE,
-    WINDOWS_PLATFORM,
 )
 from verification_notice_context import VerificationNoticeContext
 
+_subprocess_window_hooks_directory = str(Path(__file__).resolve().parents[2] / "hooks")
+if _subprocess_window_hooks_directory not in sys.path:
+    sys.path.append(_subprocess_window_hooks_directory)
+
+from hooks_constants.subprocess_window import hidden_window_creation_flags
+
 
 def start_automatic_advisory(context: VerificationNoticeContext) -> None:
     """Start the detached advisory poller when native metadata is valid."""
@@ -66,7 +70,7 @@ def _launch_advisory(
         stdin=subprocess.DEVNULL,
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL,
-        creationflags=_windows_creation_flags(),
+        creationflags=hidden_window_creation_flags(),
     )
 
 
@@ -93,8 +97,3 @@ def load_runner_configuration(
         return None
     return python_path, settings_path
 
-
-def _windows_creation_flags() -> int:
-    if sys.platform != WINDOWS_PLATFORM:
-        return 0
-    return getattr(subprocess, CREATE_NO_WINDOW_ATTRIBUTE, 0)

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -132,12 +132,14 @@ ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "pragma:",
 )
 ALL_TOKEN_ANCHORED_DIRECTIVE_BOUNDARY_CHARACTERS: frozenset[str] = frozenset({":"})
+STEALTH_KEEP_COMMENT_MARKER: str = "STEALTH: Keep"
 ALL_FREE_FORM_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "type:",
     "TODO",
     "FIXME",
     "HACK",
     "XXX",
+    STEALTH_KEEP_COMMENT_MARKER,
 )
 CHAINED_INLINE_COMMENT_PATTERN = re.compile(r"#")
 ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES: tuple[str, ...] = (

package/hooks/hooks_constants/subprocess_window.py

@@ -0,0 +1,141 @@
+"""Creation flags that keep a spawned child off the operator's screen on Windows.
+
+A hook or script often runs with no console of its own. When such a process
+starts a child on Windows, the operating system gives that child a brand new
+console, and the operator sees a black window flash open and shut while agents
+work. ``CREATE_NO_WINDOW`` tells Windows to skip that console. Every child this
+package spawns passes the flag, so the desktop stays quiet::
+
+    subprocess.run(
+        ["git", "status"],
+        creationflags=hidden_window_creation_flags(),
+    )
+
+On Windows that call returns ``0x08000000`` and no window appears. On Linux and
+macOS it returns ``0``, which is the value ``subprocess`` already uses when a
+caller passes no ``creationflags`` at all, so behaviour there is unchanged.
+``CREATE_NO_WINDOW`` is absent from a non-Windows Python build, so the lookup
+reads the attribute at call time and falls back to ``0``.
+
+``CREATE_NO_WINDOW`` gives the child a console of its own. A child that writes
+to a stream the caller redirected is unaffected, because the redirected handle
+travels with it. A child that inherits the caller's terminal instead loses that
+terminal, and the operator stops seeing its output. A few call sites hand their
+streams straight to the operator, and those pass
+``startupinfo=inherited_stream_startup_info()`` instead. That startup record
+keeps the inherited streams and hides the console window, so the operator still
+reads the output and still sees no window.
+
+``subprocess.STARTUPINFO`` is a Windows-only name. Typeshed declares it under a
+``sys.platform == "win32"`` guard, so a type check that runs on Linux, as this
+repository's continuous integration does, cannot see the name at all. The
+startup record is therefore described here as a structural ``Protocol`` naming
+the two fields this module sets, and the record itself is fetched through
+``getattr`` at call time. Both moves match what the module already does for the
+creation flags, and they keep the runtime ``sys.platform`` test in one place, so
+one function serves every platform.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import Protocol
+
+from hooks_constants.subprocess_window_constants import (
+    CREATE_NEW_PROCESS_GROUP_ATTRIBUTE,
+    CREATE_NO_WINDOW_ATTRIBUTE,
+    HIDE_WINDOW_COMMAND_ATTRIBUTE,
+    NO_CREATION_FLAGS,
+    SHOW_WINDOW_FLAG_ATTRIBUTE,
+    STARTUP_INFO_ATTRIBUTE,
+    WINDOWS_PLATFORM,
+)
+
+__all__ = [
+    "HiddenWindowStartupInfo",
+    "detached_hidden_window_creation_flags",
+    "hidden_window_creation_flags",
+    "inherited_stream_startup_info",
+]
+
+
+class HiddenWindowStartupInfo(Protocol):
+    """The two ``subprocess.STARTUPINFO`` fields that hide a child's console."""
+
+    dwFlags: int
+    wShowWindow: int
+
+
+def _windows_flag(flag_attribute_name: str) -> int:
+    """Return one Windows creation flag, or zero on any other platform.
+
+    Args:
+        flag_attribute_name: The name of a ``subprocess`` creation-flag constant.
+
+    Returns:
+        The flag value on Windows, and zero elsewhere or when the running
+        Python build does not define that constant.
+    """
+    if sys.platform != WINDOWS_PLATFORM:
+        return NO_CREATION_FLAGS
+    return int(getattr(subprocess, flag_attribute_name, NO_CREATION_FLAGS))
+
+
+def hidden_window_creation_flags() -> int:
+    """Return the creation flags that start a child without a console window.
+
+    Pass the result as the ``creationflags`` argument of ``subprocess.run``,
+    ``subprocess.Popen``, ``subprocess.check_output``, or ``subprocess.call``::
+
+        subprocess.run(["git", "rev-parse", "HEAD"],
+                       creationflags=hidden_window_creation_flags())
+
+    Returns:
+        The hidden-console flag on Windows, and zero on every other platform.
+    """
+    return _windows_flag(CREATE_NO_WINDOW_ATTRIBUTE)
+
+
+def detached_hidden_window_creation_flags() -> int:
+    """Return the creation flags for a long-lived child that outlives its parent.
+
+    A detached poller needs its own process group so a console interrupt aimed
+    at the parent never reaches it, and it needs the hidden console for the same
+    reason every other child does::
+
+        subprocess.Popen(argv,
+                         creationflags=detached_hidden_window_creation_flags())
+
+    Returns:
+        A new process group combined with the hidden-console flag on Windows,
+        and zero on every other platform.
+    """
+    return _windows_flag(CREATE_NEW_PROCESS_GROUP_ATTRIBUTE) | hidden_window_creation_flags()
+
+
+def inherited_stream_startup_info() -> HiddenWindowStartupInfo | None:
+    """Return a startup record that hides the console of a stream-inheriting child.
+
+    Use this at a call site that lets the child write straight to the operator's
+    terminal, where ``hidden_window_creation_flags`` would take that terminal
+    away::
+
+        subprocess.run(["python", "-m", "pytest"],
+                       startupinfo=inherited_stream_startup_info())
+
+    Returns:
+        A Windows startup record asking for a hidden window, and ``None`` on
+        every other platform, which is the value ``subprocess`` already uses
+        when a caller passes no ``startupinfo`` at all.
+    """
+    if sys.platform != WINDOWS_PLATFORM:
+        return None
+    startup_information = getattr(subprocess, STARTUP_INFO_ATTRIBUTE)()
+    startup_information.dwFlags |= getattr(
+        subprocess, SHOW_WINDOW_FLAG_ATTRIBUTE, NO_CREATION_FLAGS
+    )
+    startup_information.wShowWindow = getattr(
+        subprocess, HIDE_WINDOW_COMMAND_ATTRIBUTE, NO_CREATION_FLAGS
+    )
+    return startup_information

package/hooks/hooks_constants/subprocess_window_constants.py

@@ -0,0 +1,9 @@
+"""Configuration constants for the shared hidden-console creation flags."""
+
+WINDOWS_PLATFORM: str = "win32"
+CREATE_NO_WINDOW_ATTRIBUTE: str = "CREATE_NO_WINDOW"
+CREATE_NEW_PROCESS_GROUP_ATTRIBUTE: str = "CREATE_NEW_PROCESS_GROUP"
+STARTUP_INFO_ATTRIBUTE: str = "STARTUPINFO"
+SHOW_WINDOW_FLAG_ATTRIBUTE: str = "STARTF_USESHOWWINDOW"
+HIDE_WINDOW_COMMAND_ATTRIBUTE: str = "SW_HIDE"
+NO_CREATION_FLAGS: int = 0

package/hooks/hooks_constants/test_code_rules_enforcer_constants.py

@@ -17,6 +17,7 @@ if str(_HOOKS_ROOT) not in sys.path:
     sys.path.insert(0, str(_HOOKS_ROOT))
 
 from hooks_constants.code_rules_enforcer_constants import (
+    ALL_FREE_FORM_EXEMPT_COMMENT_BODIES,
     ALL_VALIDATION_PHASES,
     CONFIG_DIRECTORY_SEGMENT,
     CONSTANTS_MODULE_SUFFIX,
@@ -26,6 +27,7 @@ from hooks_constants.code_rules_enforcer_constants import (
     JSDOC_RETURNS_STRUCTURED_OBJECT_PROMISE_PATTERN,
     RETURN_CALL_OPENING_PARENTHESIS_PATTERN,
     SCHEMA_OPTIONS_PROPERTY_KEY_PATTERN,
+    STEALTH_KEEP_COMMENT_MARKER,
     UNKNOWN_VALIDATION_PHASE_MESSAGE_TEMPLATE,
     apply_edits,
     edits_for_tool,
@@ -106,6 +108,10 @@ def test_constants_module_suffix_and_config_directory_segment_are_defined() -> N
     assert CONFIG_DIRECTORY_SEGMENT == "config"
 
 
+def test_free_form_exempt_comment_bodies_include_stealth_keep_marker() -> None:
+    assert STEALTH_KEEP_COMMENT_MARKER in ALL_FREE_FORM_EXEMPT_COMMENT_BODIES
+
+
 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(