claude-dev-env 2.30.0 → 2.31.0

package/hooks/blocking/test_write_existing_file_blocker.py

@@ -0,0 +1,122 @@
+"""Tests for the write_existing_file_blocker hook.
+
+Each case drives the real hook's ``main()`` through its production stdin path,
+feeding it the PreToolUse JSON payload Claude Code sends and reading the
+permission decision back off stdout.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+from collections.abc import Mapping
+from pathlib import Path
+
+import pytest
+
+import write_existing_file_blocker
+
+
+def _run_payload(
+    payload: Mapping[str, object],
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> str:
+    """Run the real hook entry point and return its stdout."""
+    monkeypatch.setattr(write_existing_file_blocker.sys, "stdin", io.StringIO(json.dumps(payload)))
+    with contextlib.suppress(SystemExit):
+        write_existing_file_blocker.main()
+    return capsys.readouterr().out
+
+
+def _is_deny(stdout_text: str) -> bool:
+    if not stdout_text.strip():
+        return False
+    decision = json.loads(stdout_text)
+    return decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_write_denies_an_existing_target(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A Write onto a path that already exists is denied."""
+    existing_path = tmp_path / "already_here.py"
+    existing_path.write_text("x = 1\n", encoding="utf-8")
+    payload = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(existing_path), "content": "x = 2\n"},
+    }
+
+    stdout = _run_payload(payload, monkeypatch, capsys)
+
+    assert _is_deny(stdout), f"expected a deny, got {stdout!r}"
+
+
+def test_apply_patch_add_denies_an_existing_target(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """An apply_patch 'Add File' section targeting an existing path is denied."""
+    existing_path = tmp_path / "already_here.py"
+    existing_path.write_text("x = 1\n", encoding="utf-8")
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(tmp_path),
+        "tool_input": {
+            "command": ("*** Begin Patch\n*** Add File: already_here.py\n+x = 2\n*** End Patch")
+        },
+    }
+
+    stdout = _run_payload(payload, monkeypatch, capsys)
+
+    assert _is_deny(stdout), f"expected a deny, got {stdout!r}"
+
+
+def test_apply_patch_update_on_an_existing_target_is_allowed(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """An 'Update File' section on an existing path is not an unread overwrite."""
+    existing_path = tmp_path / "already_here.py"
+    existing_path.write_text("x = 1\n", encoding="utf-8")
+    payload = {
+        "tool_name": "apply_patch",
+        "cwd": str(tmp_path),
+        "tool_input": {
+            "command": (
+                "*** Begin Patch\n"
+                "*** Update File: already_here.py\n"
+                "@@\n"
+                "-x = 1\n"
+                "+x = 2\n"
+                "*** End Patch"
+            )
+        },
+    }
+
+    stdout = _run_payload(payload, monkeypatch, capsys)
+
+    assert not _is_deny(stdout), f"expected an allow, got {stdout!r}"
+
+
+def test_multi_edit_on_an_existing_target_is_allowed(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """A MultiEdit always targets a file already on disk, so it is never denied here.
+
+    Every MultiEdit edit must match an ``old_string`` already present in the
+    file, so MultiEdit carries no blind create-or-clobber path the way a Write
+    or an apply_patch 'Add File' does — this hook allows it unconditionally.
+    """
+    existing_path = tmp_path / "already_here.py"
+    existing_path.write_text("x = 1\n", encoding="utf-8")
+    payload = {
+        "tool_name": "MultiEdit",
+        "tool_input": {
+            "file_path": str(existing_path),
+            "edits": [{"old_string": "x = 1", "new_string": "x = 2"}],
+        },
+    }
+
+    stdout = _run_payload(payload, monkeypatch, capsys)
+
+    assert not _is_deny(stdout), f"expected an allow, got {stdout!r}"

package/hooks/blocking/windows_rmtree_blocker.py

@@ -17,13 +17,22 @@ import re
 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.hook_block_logger import log_hook_block  # noqa: E402
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin  # noqa: E402
-from hooks_constants.windows_rmtree_blocker_constants import PYTHON_FILE_EXTENSION  # noqa: E402
+try:
+    _hooks_dir = str(Path(__file__).resolve().parent.parent)
+    if _hooks_dir not in sys.path:
+        sys.path.insert(0, _hooks_dir)
+
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.multi_edit_reconstruction import joined_new_strings
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.windows_rmtree_blocker_constants import (
+        PYTHON_FILE_EXTENSION,
+    )
+except ImportError as import_error:
+    raise ImportError(
+        "windows_rmtree_blocker: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
 
 
 def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
@@ -37,6 +46,11 @@ def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
 
 
 def extract_payload_text(tool_name: str, tool_input: dict) -> str:
+    if tool_name == "MultiEdit":
+        file_path = tool_input.get("file_path", "")
+        if file_path and not file_path.endswith(PYTHON_FILE_EXTENSION):
+            return ""
+        return joined_new_strings(tool_input)
     if tool_name in {"Write", "Edit"}:
         file_path = tool_input.get("file_path", "")
         if file_path and not file_path.endswith(PYTHON_FILE_EXTENSION):

package/hooks/blocking/write_existing_file_blocker.py

@@ -1,8 +1,14 @@
 #!/usr/bin/env python3
-"""PreToolUse:Write hook — blocks Write tool when the target file already exists.
+"""PreToolUse hook — blocks Write and apply_patch "Add File" onto an existing target.
 
-Agents should use Edit for modifying existing files. Write is only for new file creation.
+Agents should use Edit for modifying existing files, and an apply_patch
+"Update File" section rather than "Add File" for a path that already exists.
 Exemptions: Jupyter notebooks (.ipynb) and files in ~/.claude/hooks/ (standalone scripts).
+
+MultiEdit carries no create-or-clobber path this hook needs to guard: every
+MultiEdit edit must match an ``old_string`` already present in the target file,
+so a MultiEdit can never introduce content nobody read the way a blind Write or
+an apply_patch "Add File" can. This hook allows MultiEdit unconditionally.
 """
 
 import json
@@ -14,7 +20,22 @@ _hooks_dir = str(Path(__file__).resolve().parent.parent)
 if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+try:
+    from codex_apply_patch import (
+        CODEX_ADD_OPERATION,
+        CodexPatchError,
+        codex_patch_operation_targets,
+        payload_patch_command,
+    )
+    from hooks_constants.hook_block_logger import log_hook_block
+    from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+    from hooks_constants.pre_tool_use_dispatcher_constants import APPLY_PATCH_TOOL_NAME
+    from sensitive_file_protector import build_deny_response
+except ImportError as import_error:
+    raise ImportError(
+        "write_existing_file_blocker: cannot import its sibling modules; "
+        "ensure the hooks directory is importable."
+    ) from import_error
 
 JUPYTER_EXTENSION = ".ipynb"
 HOOKS_DIRECTORY = os.path.normpath(os.path.expanduser("~/.claude/hooks"))
@@ -29,48 +50,73 @@ def is_inside_hooks_directory(file_path: str) -> bool:
     return normalized_path.startswith(HOOKS_DIRECTORY)
 
 
-def main() -> None:
+def _apply_patch_add_deny(payload: dict, tool_input: dict) -> tuple[str, str] | None:
+    """Return (deny_reason, offending_path) for an apply_patch 'Add File' onto an existing path."""
+    command, working_directory = payload_patch_command(payload, tool_input)
+    if not command:
+        return None
     try:
-        input_payload = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
+        all_operation_targets = codex_patch_operation_targets(command, working_directory)
+    except CodexPatchError:
+        return None
+    for each_operation, each_target_path in all_operation_targets:
+        if each_operation != CODEX_ADD_OPERATION:
+            continue
+        if os.path.exists(each_target_path):
+            deny_reason = (
+                f"BLOCKED: apply_patch 'Add File' on existing file {each_target_path}. "
+                "Use an 'Update File' section instead."
+            )
+            return deny_reason, each_target_path
+    return None
+
+
+def _write_onto_existing_file_deny(tool_input: dict) -> tuple[str, str] | None:
+    """Return (deny_reason, offending_path) for a Write onto an existing target."""
+    target_file_path = tool_input.get("file_path", "")
+    if not target_file_path:
+        return None
+    if is_jupyter_notebook(target_file_path):
+        return None
+    if is_inside_hooks_directory(target_file_path):
+        return None
+    if not os.path.exists(target_file_path):
+        return None
+    deny_reason = f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead."
+    return deny_reason, target_file_path
 
-    tool_name = input_payload.get("tool_name", "")
-    tool_input = input_payload.get("tool_input", {})
 
+def _resolve_deny(tool_name: str, payload: dict, tool_input: dict) -> tuple[str, str] | None:
+    """Return (deny_reason, offending_path) for the payload, or None to allow."""
+    if tool_name == APPLY_PATCH_TOOL_NAME:
+        return _apply_patch_add_deny(payload, tool_input)
     if tool_name != "Write":
-        sys.exit(0)
+        return None
+    return _write_onto_existing_file_deny(tool_input)
 
-    target_file_path = tool_input.get("file_path", "")
 
-    if not target_file_path:
-        sys.exit(0)
-
-    if is_jupyter_notebook(target_file_path):
+def main() -> None:
+    input_payload = read_hook_input_dictionary_from_stdin()
+    if input_payload is None:
         sys.exit(0)
 
-    if is_inside_hooks_directory(target_file_path):
-        sys.exit(0)
+    raw_tool_name = input_payload.get("tool_name", "")
+    raw_tool_input = input_payload.get("tool_input", {})
+    tool_name = raw_tool_name if isinstance(raw_tool_name, str) else ""
+    tool_input = raw_tool_input if isinstance(raw_tool_input, dict) else {}
 
-    if not os.path.exists(target_file_path):
+    resolved_deny = _resolve_deny(tool_name, input_payload, tool_input)
+    if resolved_deny is None:
         sys.exit(0)
+    deny_reason, offending_path = resolved_deny
 
-    deny_reason = f"BLOCKED: Write on existing file {target_file_path}. Use Edit tool instead."
-    denial = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": deny_reason,
-        }
-    }
     log_hook_block(
         calling_hook_name="write_existing_file_blocker.py",
         hook_event="PreToolUse",
         block_reason=deny_reason,
-        tool_name="Write",
-        offending_input_preview=target_file_path,
+        offending_input_preview=offending_path,
     )
-    print(json.dumps(denial))
+    print(json.dumps(build_deny_response(deny_reason)))
     sys.exit(0)
 
 

package/hooks/conftest.py

@@ -0,0 +1,47 @@
+"""Shared pytest fixtures for the hooks/ suite, visible under blocking/ and validators/."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+import pytest
+
+_HOOKS_DIRECTORY = Path(__file__).resolve().parent
+_BLOCKING_DIRECTORY = _HOOKS_DIRECTORY / "blocking"
+for each_directory in (_HOOKS_DIRECTORY, _BLOCKING_DIRECTORY):
+    if str(each_directory) not in sys.path:
+        sys.path.insert(0, str(each_directory))
+
+_is_ephemeral_script_path = importlib.import_module("code_rules_shared").is_ephemeral_script_path
+_EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME = importlib.import_module(
+    "hooks_constants.code_rules_enforcer_constants"
+).EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME
+
+_ROOT_ANCHORED_PROBE_PATH = "/tmp/scratch.py"
+
+
+@pytest.fixture
+def ephemeral_exempt_off(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Turn off the ephemeral scratch-path exemption for the current test.
+
+    Sets ``CLAUDE_CODE_RULES_DISABLE_EPHEMERAL_EXEMPT`` so a gate under test
+    judges the test's own scratch targets for real, rather than stepping aside
+    because they sit under a temp root.
+
+    The probe path is root-anchored ``/tmp``, which the classifier treats as
+    ephemeral on every platform, so the assert fails on any change that stops
+    reading the disable flag. A probe on the shared OS temp root would pass on
+    Windows whether the flag is read or not, since the classifier already
+    excludes that root by design.
+
+    Args:
+        monkeypatch: Pytest's environment-variable patcher, torn down after the test.
+    """
+    monkeypatch.setenv(_EPHEMERAL_EXEMPT_DISABLE_ENVIRONMENT_VARIABLE_NAME, "1")
+    assert _is_ephemeral_script_path(_ROOT_ANCHORED_PROBE_PATH) is False, (
+        "ephemeral_exempt_off must turn off the scratch-path exemption; a change "
+        "that stops reading the disable flag must fail here, not silently return "
+        "every test in the file to deciding nothing"
+    )

package/hooks/hooks.json

@@ -13,7 +13,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|MultiEdit",
+        "matcher": "Write|Edit|MultiEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -22,16 +22,6 @@
           }
         ]
       },
-      {
-        "matcher": "apply_patch",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py",
-            "timeout": 60
-          }
-        ]
-      },
       {
         "matcher": "Bash|PowerShell",
         "hooks": [
@@ -171,7 +161,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
           },
           {
@@ -245,7 +235,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit|MultiEdit",
+        "matcher": "Write|Edit|MultiEdit|apply_patch",
         "hooks": [
           {
             "type": "command",
@@ -261,6 +251,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/investigation_tracker_reset.py",
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/observability/pr_description_writer_spawn_tracker.py",
+            "timeout": 30
           }
         ]
       },

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -76,4 +76,7 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry("blocking/test_preflight_check.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/windows_rmtree_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/gh_pr_author_enforcer.py", ALL_BASH_ONLY_TOOL_NAMES),
+    BashHostedHookEntry(
+        "blocking/pr_description_writer_gate.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES
+    ),
 )

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -6,8 +6,11 @@ Extracted from code_rules_enforcer.py to satisfy the constants-location rule.
 import re
 import tokenize
 
+from hooks_constants.multi_edit_reconstruction import (  # noqa: F401  re-exported for code_rules_enforcer.py
+    apply_edits,
+    edits_for_tool,
+)
 from hooks_constants.validation_phase_constants import (  # noqa: F401  re-exported for code_rules_enforcer.py
-    ALL_HOOK_INFRASTRUCTURE_EDIT_LANE_CHECK_NAMES,
     ALL_VALIDATION_PHASES,
     EDIT_LANE_PHASE,
     FULL_GATE_PHASE,

package/hooks/hooks_constants/duplicate_rmtree_helper_blocker_constants.py

@@ -24,3 +24,6 @@ ALL_EXEMPT_PATH_FRAGMENTS: tuple[str, ...] = (
 
 ALL_EXEMPT_TEST_FILE_PREFIXES: tuple[str, ...] = ("test_",)
 ALL_EXEMPT_TEST_FILE_SUFFIXES: tuple[str, ...] = ("_test.py",)
+
+
+ALL_APPLICABLE_TOOL_NAMES: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})

package/hooks/hooks_constants/hook_prose_detector_consistency_constants.py

@@ -1,7 +1,12 @@
 """Configuration constants for the hook_prose_detector_consistency PreToolUse hook."""
 
-WRITE_TOOL_NAME: str = "Write"
-EDIT_TOOL_NAME: str = "Edit"
+# The dispatcher constants module is the single source for tool names.
+from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: F401
+    EDIT_TOOL_NAME,
+    MULTI_EDIT_TOOL_NAME,
+    WRITE_TOOL_NAME,
+)
+
 
 HOOK_MODULE_PATH_SEGMENT: str = "/hooks/"
 PYTHON_FILE_SUFFIX: str = ".py"

package/hooks/hooks_constants/migration_safety_advisor_constants.py

@@ -0,0 +1,7 @@
+"""Configuration constants for the migration_safety_advisor PreToolUse hook."""
+
+# The dispatcher constants module is the single source for tool names.
+from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: F401
+    MULTI_EDIT_TOOL_NAME,
+)
+

package/hooks/hooks_constants/multi_edit_reconstruction.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 __all__ = [
     "apply_edits",
     "edits_for_tool",
+    "joined_new_strings",
 ]
 
 
@@ -24,9 +25,19 @@ def apply_edits(existing_content: str, all_edits: list[dict]) -> str:
             ``edits`` list, each a mapping with an ``old_string`` and a
             ``new_string``.
 
+    An edit carrying ``replace_all`` rewrites every occurrence, matching what
+    MultiEdit itself does; every other edit rewrites the first one::
+
+        {"old_string": "old", "new_string": "new", "replace_all": True}
+            "old old old"  ->  "new new new"
+        {"old_string": "old", "new_string": "new"}
+            "old old old"  ->  "new old old"
+
+    Each edit reads its own flag, so one replace_all edit in a list leaves the
+    edits beside it alone.
+
     Returns:
-        The content after replacing the first occurrence of each edit's
-        ``old_string`` with its ``new_string``, in list order.
+        The content after applying each edit in list order.
     """
     edited_content = existing_content
     for each_edit in all_edits:
@@ -35,7 +46,10 @@ def apply_edits(existing_content: str, all_edits: list[dict]) -> str:
         old_string = each_edit.get("old_string", "")
         new_string = each_edit.get("new_string", "")
         if isinstance(old_string, str) and isinstance(new_string, str) and old_string:
-            edited_content = edited_content.replace(old_string, new_string, 1)
+            is_replace_all = bool(each_edit.get("replace_all"))
+            edited_content = edited_content.replace(
+                old_string, new_string, -1 if is_replace_all else 1
+            )
     return edited_content
 
 
@@ -54,3 +68,30 @@ def edits_for_tool(tool_name: str, tool_input: dict) -> list[dict]:
         return [tool_input]
     all_edits = tool_input.get("edits", [])
     return all_edits if isinstance(all_edits, list) else []
+
+
+def joined_new_strings(tool_input: dict) -> str:
+    """Return one scannable text holding every string a MultiEdit introduces.
+
+    ::
+
+        edits = [{"new_string": "import os"}, {"new_string": "shutil.rmtree(p)"}]
+        joined_new_strings(...)  ->  "import os\\nshutil.rmtree(p)"
+
+    A blocker scans that single text in one pass. The joining newline keeps one
+    edit's last line apart from the next edit's first line, so a phrase neither
+    edit wrote never appears across the seam.
+
+    Args:
+        tool_input: The MultiEdit tool input payload.
+
+    Returns:
+        Every string-valued new_string in the payload, joined on a newline.
+    """
+    multi_edit_new_string_join_separator = "\n"
+    all_new_strings = [
+        each_edit.get("new_string", "")
+        for each_edit in edits_for_tool("MultiEdit", tool_input)
+        if isinstance(each_edit, dict) and isinstance(each_edit.get("new_string"), str)
+    ]
+    return multi_edit_new_string_join_separator.join(all_new_strings)

package/hooks/hooks_constants/pii_prevention_constants.py

@@ -6,15 +6,17 @@ import re
 
 from hooks_constants.hardcoded_user_path_constants import HARDCODED_USER_PATH_PATTERN
 
+# The dispatcher constants module is the single source for tool names.
+from hooks_constants.pre_tool_use_dispatcher_constants import (  # noqa: F401
+    ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES,
+    APPLY_PATCH_TOOL_NAME,
+    EDIT_TOOL_NAME,
+    MULTI_EDIT_TOOL_NAME,
+    WRITE_TOOL_NAME,
+)
+
 BASH_TOOL_NAME: str = "Bash"
 POWERSHELL_TOOL_NAME: str = "PowerShell"
-WRITE_TOOL_NAME: str = "Write"
-EDIT_TOOL_NAME: str = "Edit"
-MULTI_EDIT_TOOL_NAME: str = "MultiEdit"
-
-ALL_WRITE_EDIT_MULTI_EDIT_TOOL_NAMES: frozenset[str] = frozenset(
-    {WRITE_TOOL_NAME, EDIT_TOOL_NAME, MULTI_EDIT_TOOL_NAME}
-)
 
 ALL_SHELL_TOOL_NAMES: frozenset[str] = frozenset(
     {BASH_TOOL_NAME, POWERSHELL_TOOL_NAME}

package/hooks/hooks_constants/pr_description_writer_gate_constants.py

@@ -0,0 +1,39 @@
+"""Constants for the pr-description-writer spawn tracker and its gh pr create gate.
+
+The tracker records one fact per session: the session spawned the
+``pr-description-writer`` agent. The gate reads that fact when the session runs
+``gh pr create`` and denies the command when the fact is absent.
+"""
+
+from __future__ import annotations
+
+PR_DESCRIPTION_WRITER_SUBAGENT_TYPE: str = "pr-description-writer"
+
+ALL_AGENT_SPAWN_TOOL_NAMES: frozenset[str] = frozenset({"Agent", "Task"})
+
+SPAWN_MARKER_FILE_PREFIX: str = "claude-session-pr-description-writer-"
+SPAWN_MARKER_FILE_SUFFIX: str = ".marker"
+
+SUBAGENT_TYPE_FIELD_NAME: str = "subagent_type"
+TOOL_INPUT_FIELD_NAME: str = "tool_input"
+TOOL_NAME_FIELD_NAME: str = "tool_name"
+COMMAND_FIELD_NAME: str = "command"
+
+ALL_GH_EXECUTABLE_BASENAMES: frozenset[str] = frozenset({"gh", "gh.exe", "gh.cmd"})
+PR_SUBCOMMAND_TOKEN: str = "pr"
+CREATE_SUBCOMMAND_TOKEN: str = "create"
+GH_PR_CREATE_MINIMUM_TOKEN_COUNT: int = 3
+
+SPAWN_BYPASS_MARKER: str = "# pr-description-skip"
+
+CORRECTIVE_MESSAGE: str = (
+    "BLOCKED: [PR_DESCRIPTION_WRITER] This session runs `gh pr create` with no "
+    "`pr-description-writer` agent spawn recorded.\n\n"
+    "The agent writes the title and body from the current diff, then returns the "
+    "markdown and a body-file path for you to publish.\n\n"
+    "Two ways forward:\n"
+    "  1. Spawn the agent (Agent tool, subagent_type `pr-description-writer`), "
+    "then run `gh pr create --body-file <path>` with what it returns.\n"
+    "  2. Append the trailing comment `# pr-description-skip` to the command when "
+    "you are writing the body yourself on purpose."
+)