claude-dev-env 8.23.2 → 8.25.0

package/docs/CODE_RULES.md

@@ -13,6 +13,8 @@ Do not add code comments. Preserve existing comments. Docstrings remain allowed.
 When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
 Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed rather than added or justified.
 
+A keep marker is the one comment that may be added and kept: a comment that opens with `STEALTH: Keep`, or with a prefix the repository lists under `comment_keep_markers` in `.claude/policy-lint.json`.
+
 ---
 
 ## CORE PRINCIPLES

package/hooks/blocking/code_rules_comments.py

@@ -1,8 +1,10 @@
 """Comment-presence and comment-change checks for Python and JavaScript sources."""
 
 import difflib
+import functools
 import importlib
 import io
+import json
 import sys
 import tokenize
 from collections import Counter
@@ -29,7 +31,11 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_TOKEN_ANCHORED_DIRECTIVE_BOUNDARY_CHARACTERS,
     ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES,
     CHAINED_INLINE_COMMENT_PATTERN,
+    COMMENT_KEEP_MARKERS_KEY,
     MAX_COMMENT_ISSUES,
+    REPOSITORY_LINT_SETTINGS_RELATIVE_PATH,
+    REPOSITORY_ROOT_MARKER_NAME,
+    SETTINGS_TEXT_ENCODING,
     STEALTH_KEEP_COMMENT_MARKER,
 )
 _javascript_comment_scanner = importlib.import_module("javascript_comment_scanner")
@@ -153,27 +159,70 @@ def _python_comment_occurrences(
     return all_occurrences, True
 
 
-def _is_stealth_keep_occurrence(comment_text: str) -> bool:
-    """Return True for a ``# STEALTH: Keep`` occurrence.
+@functools.cache
+def _repository_keep_markers(repository_root: Path) -> tuple[str, ...]:
+    settings_path = repository_root / REPOSITORY_LINT_SETTINGS_RELATIVE_PATH
+    try:
+        all_settings = json.loads(settings_path.read_text(encoding=SETTINGS_TEXT_ENCODING))
+    except (OSError, ValueError):
+        return ()
+    if not isinstance(all_settings, dict):
+        return ()
+    all_markers = all_settings.get(COMMENT_KEEP_MARKERS_KEY)
+    if not isinstance(all_markers, list):
+        return ()
+    return tuple(each for each in all_markers if isinstance(each, str) and each)
+
+
+def comment_keep_markers(file_path: str) -> tuple[str, ...]:
+    """Return the comment prefixes the comment-change check accepts for a file.
+
+    ::
+
+        repo/.claude/policy-lint.json  {"comment_keep_markers": ["VENDOR: Keep"]}
+        repo/app/main.py               ("STEALTH: Keep", "VENDOR: Keep")
+        no settings file               ("STEALTH: Keep",)
+
+    The repository that holds the file names its own markers. A missing or
+    unreadable settings file adds none.
+
+    Args:
+        file_path: The path of the file under check.
+
+    Returns:
+        The package's built-in marker, then the markers the file's repository
+        adds.
+    """
+    for each_directory in Path(file_path).resolve().parents:
+        if (each_directory / REPOSITORY_ROOT_MARKER_NAME).exists():
+            return (
+                STEALTH_KEEP_COMMENT_MARKER,
+                *_repository_keep_markers(each_directory),
+            )
+    return (STEALTH_KEEP_COMMENT_MARKER,)
+
+
+def _is_keep_occurrence(comment_text: str, all_keep_markers: tuple[str, ...]) -> bool:
+    """Return True for a comment that opens with an accepted keep marker.
 
-    ``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.
+    A keep marker 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
+        all_keep_markers
     )
 
 
-def _without_stealth_keep_occurrences(
-    all_occurrences: list[tuple[str, int, bool]]
+def _without_keep_occurrences(
+    all_occurrences: list[tuple[str, int, bool]], all_keep_markers: tuple[str, ...]
 ) -> list[tuple[str, int, bool]]:
     return [
         each_occurrence
         for each_occurrence in all_occurrences
-        if not _is_stealth_keep_occurrence(each_occurrence[0])
+        if not _is_keep_occurrence(each_occurrence[0], all_keep_markers)
     ]
 
 
@@ -181,8 +230,10 @@ def check_comment_changes(old_content: str, new_content: str, file_path: str) ->
     """Check for comment additions or removals between old and new content.
 
     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.
+    keep-marker occurrences (``STEALTH: Keep`` and any marker the file's
+    repository names in ``.claude/policy-lint.json``), 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
@@ -205,8 +256,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)
+    all_keep_markers = comment_keep_markers(file_path)
+    old_occurrences = _without_keep_occurrences(old_occurrences, all_keep_markers)
+    new_occurrences = _without_keep_occurrences(new_occurrences, all_keep_markers)
 
     old_occurrence_counts = Counter(
         (each_text, is_inline)
@@ -294,8 +346,9 @@ 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_keep_markers = comment_keep_markers(file_path)
+    old_occurrences = _without_keep_occurrences(old_occurrences, all_keep_markers)
+    new_occurrences = _without_keep_occurrences(new_occurrences, all_keep_markers)
     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]

package/hooks/blocking/reply_length_gate.py

@@ -4,6 +4,11 @@
 The gate reads the ``text`` field of the chat tools that post to the user.
 It denies the call when the text holds more than MAXIMUM_SENTENCE_COUNT
 sentences, or a sentence longer than MAXIMUM_WORDS_PER_SENTENCE words.
+It also denies a pull request number the reader cannot open::
+
+    flag: Both land in PR 5256.
+    flag: It merged in #4347.
+    ok:   Both land in [PR 5256](https://github.com/owner/repo/pull/5256).
 Each non-empty line counts as its own sentence, so a list counts one
 sentence per item. URLs, markdown link targets, inline code spans, and
 fenced blocks carry no words.
@@ -34,6 +39,7 @@ from hooks_constants.reply_length_gate_constants import (
     LINE_BREAK_PATTERN,
     LINK_TARGET_PATTERN,
     LONG_SENTENCE_MESSAGE,
+    MARKDOWN_LINK_PATTERN,
     MAXIMUM_SENTENCE_COUNT,
     MAXIMUM_WORDS_PER_SENTENCE,
     RETRY_INSTRUCTION,
@@ -44,6 +50,8 @@ from hooks_constants.reply_length_gate_constants import (
     TOO_MANY_SENTENCES_MESSAGE,
     TOOL_INPUT_KEY,
     TOOL_NAME_KEY,
+    UNLINKED_PULL_REQUEST_MESSAGE,
+    UNLINKED_PULL_REQUEST_PATTERN,
     URL_PATTERN,
     WORD_PATTERN,
     WORD_SEPARATOR,
@@ -87,6 +95,17 @@ def length_violation(reply_text: str) -> str | None:
     return None
 
 
+def unlinked_pull_request_violation(reply_text: str) -> str | None:
+    """Return the deny reason for a pull request number outside a link, or None."""
+    without_fences = FENCED_BLOCK_PATTERN.sub(" ", reply_text)
+    without_code = INLINE_CODE_PATTERN.sub(" ", without_fences)
+    without_links = MARKDOWN_LINK_PATTERN.sub(" ", without_code)
+    unlinked_match = UNLINKED_PULL_REQUEST_PATTERN.search(URL_PATTERN.sub(" ", without_links))
+    if unlinked_match is None:
+        return None
+    return UNLINKED_PULL_REQUEST_MESSAGE.format(reference=unlinked_match.group(0))
+
+
 def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None:
@@ -100,7 +119,7 @@ def main() -> int:
     reply_text = tool_input.get(TEXT_KEY)
     if not isinstance(reply_text, str):
         return ALLOW_EXIT_CODE
-    violation = length_violation(reply_text)
+    violation = length_violation(reply_text) or unlinked_pull_request_violation(reply_text)
     if violation is None:
         return ALLOW_EXIT_CODE
     block_reason = violation + RETRY_INSTRUCTION

package/hooks/blocking/test_code_rules_enforcer_comment_string_awareness.py

@@ -13,6 +13,7 @@ a string still flag.
 
 from __future__ import annotations
 
+import json
 import sys
 import importlib
 from pathlib import Path
@@ -413,3 +414,46 @@ def test_check_comment_changes_accepts_distant_untouched_comment() -> None:
     new_content = "# TODO #999: distant note\n\ntotal = 2\n"
     issues = code_rules_enforcer.check_comment_changes(old_content, new_content, "totals.py")
     assert not any("still on the changed lines" in each_issue for each_issue in issues)
+
+
+def _repository_file(tmp_path: Path, all_keep_markers: list[str] | None) -> str:
+    (tmp_path / ".git").mkdir()
+    if all_keep_markers is not None:
+        (tmp_path / ".claude").mkdir()
+        (tmp_path / ".claude" / "policy-lint.json").write_text(
+            json.dumps({"comment_keep_markers": all_keep_markers}), encoding="utf-8"
+        )
+    return str(tmp_path / "app" / "main.py")
+
+
+def test_check_comment_changes_accepts_a_marker_the_repository_names(
+    tmp_path: Path,
+) -> None:
+    file_path = _repository_file(tmp_path, ["VENDOR: Keep"])
+    issues = code_rules_enforcer.check_comment_changes(
+        "x = 1\n", "x = 1  # VENDOR: Keep -- reason\n", file_path
+    )
+    assert issues == []
+
+
+def test_check_comment_changes_flags_that_marker_in_a_repository_without_it(
+    tmp_path: Path,
+) -> None:
+    file_path = _repository_file(tmp_path, None)
+    issues = code_rules_enforcer.check_comment_changes(
+        "x = 1\n", "x = 1  # VENDOR: Keep -- reason\n", file_path
+    )
+    assert len(issues) == 1
+    assert "comment added" in issues[0]
+
+
+def test_check_comment_changes_accepts_a_retained_repository_marker_on_a_touched_line(
+    tmp_path: Path,
+) -> None:
+    file_path = _repository_file(tmp_path, ["VENDOR: Keep"])
+    issues = code_rules_enforcer.check_comment_changes(
+        "x = 1  # VENDOR: Keep -- reason\n",
+        "x = 2  # VENDOR: Keep -- reason\n",
+        file_path,
+    )
+    assert issues == []

package/hooks/blocking/test_reply_length_gate.py

@@ -191,3 +191,47 @@ def test_should_allow_a_call_without_text(
 def test_should_allow_empty_stdin(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"")))
     assert reply_length_gate.main() == 0
+
+
+def test_should_deny_a_pr_number_with_no_link_and_name_it(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": "Both land in PR 5256."}
+    )
+    assert exit_code == 2
+    assert "PR 5256" in stderr_text
+
+
+def test_should_deny_a_bare_hash_number(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, POST_TOOL_NAME, {"text": "It merged in #4347."}
+    )
+    assert exit_code == 2
+    assert "#4347" in stderr_text
+
+
+def test_should_allow_a_pr_number_inside_its_link(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Both land in [PR 5256](https://github.com/owner/repo/pull/5256)."},
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_allow_a_bare_pull_request_url(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Pull request: https://github.com/owner/repo/pull/5256"},
+    )
+    assert exit_code == 0

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -136,6 +136,10 @@ ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
 )
 ALL_TOKEN_ANCHORED_DIRECTIVE_BOUNDARY_CHARACTERS: frozenset[str] = frozenset({":"})
 STEALTH_KEEP_COMMENT_MARKER: str = "STEALTH: Keep"
+REPOSITORY_LINT_SETTINGS_RELATIVE_PATH: str = ".claude/policy-lint.json"
+COMMENT_KEEP_MARKERS_KEY: str = "comment_keep_markers"
+REPOSITORY_ROOT_MARKER_NAME: str = ".git"
+SETTINGS_TEXT_ENCODING: str = "utf-8"
 ALL_FREE_FORM_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "type:",
     "TODO",

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -15,6 +15,10 @@ FENCED_BLOCK_PATTERN = re.compile(r"```.*?(?:```|\Z)", re.DOTALL)
 INLINE_CODE_PATTERN = re.compile(r"`[^`\n]*`")
 LINK_TARGET_PATTERN = re.compile(r"\]\([^)\s]*\)")
 URL_PATTERN = re.compile(r"(?:https?://|www\.)\S+")
+MARKDOWN_LINK_PATTERN = re.compile(r"\[[^\]\n]*\]\([^)\s]*\)")
+UNLINKED_PULL_REQUEST_PATTERN = re.compile(
+    r"\b(?:PRs?|pull requests?)\s*#?\d+|(?<![\w/&])#\d+", re.IGNORECASE
+)
 LINE_BREAK_PATTERN = re.compile(r"\n+")
 SENTENCE_END_PATTERN = re.compile(r"(?<=[.!?])\s+")
 WORD_PATTERN = re.compile(r"[A-Za-z0-9]+(?:['.,-][A-Za-z0-9]+)*")
@@ -23,6 +27,7 @@ WORD_SEPARATOR = " "
 SENTENCE_PREVIEW_SUFFIX = "..."
 RETRY_INSTRUCTION = " Cut the text and resend the call."
 TOO_MANY_SENTENCES_MESSAGE = "Reply too long: {sentence_count} sentences, limit {sentence_limit}."
+UNLINKED_PULL_REQUEST_MESSAGE = 'Pull request "{reference}" has no link. Write it as [PR N](https://github.com/<owner>/<repo>/pull/N).'
 LONG_SENTENCE_MESSAGE = (
     'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
 )

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.23.2",
+    "version": "8.25.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/review-closure-is-a-check.md

@@ -33,6 +33,8 @@ A red circle marks a finding a review states as blocking, so resolution in silen
 
 The driving account is the one that opened the pull request. Where the agent comments under a second login, `--driver-login <login>` names it, repeatably.
 
+A repository whose review bots post notices this package does not know passes each one's marker text with `--notice-marker <text>`, repeatably. A bot comment carrying that text closes itself, like the built-in notices above.
+
 ## Where the check runs
 
 `.github/workflows/review-closure.yml` runs it here on a push to a pull request, on a submitted or dismissed review, on a review comment, and on a top-level comment posted or edited on a pull request. Each run reports on the pull request's head commit, so a finding posted after the last push still turns the check red.

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -131,6 +131,12 @@ EXIT_FALLTHROUGH: int = 1
 CLI_ROLE_FLAG: str = "--role"
 """CLI flag naming the role whose agent definition set must be present."""
 
+CLI_AGENT_FLAG: str = "--agent"
+"""CLI flag naming the agent definition stem that serves an unregistered role."""
+
+AGENT_DEFINITION_SUFFIX: str = ".md"
+"""File suffix of an agent definition under ``agents/``."""
+
 CLI_PING_FLAG: str = "--ping"
 """CLI flag that enables the opt-in cached live single-turn ping."""
 

package/scripts/dev_env_scripts_constants/review_closure_constants.py

@@ -203,6 +203,12 @@ DRIVER_LOGIN_ARGUMENT_HELP: str = (
 )
 """Help text for the driver login argument."""
 
+NOTICE_MARKER_ARGUMENT_HELP: str = (
+    "Text that marks a bot comment as a notice on this repository, beside the "
+    "built-in markers. Repeatable."
+)
+"""Help text for the notice marker argument."""
+
 CLOSED_VERDICT_LABEL: str = "CLOSED"
 """Verdict label for a pull request with every finding answered."""
 

package/scripts/grok_worker_preflight.py

@@ -12,7 +12,8 @@ Checks run in order and stop at the first failure:
    running workers.
 3. ``claude-dev-env`` is installed for the requested role: the install manifest
    exists in the user Claude config directory, and every agent definition file
-   that role needs is present under ``agents/``.
+   that role needs is present under ``agents/``. A caller that names its own
+   agent needs that one definition file.
 
 Opt-in ``--ping`` runs one cached live single-turn call with a run-scoped TTL.
 The cache file lives under the caller-supplied run state directory. Auth failure
@@ -54,6 +55,7 @@ from dataclasses import dataclass
 from pathlib import Path
 
 from dev_env_scripts_constants.grok_worker_constants import (
+    AGENT_DEFINITION_SUFFIX,
     AGENTS_SUBDIRECTORY,
     ALL_AGENT_FILENAMES_BY_ROLE,
     ALL_AUTH_FAILURE_SIGNATURES,
@@ -277,14 +279,20 @@ def _is_grok_binary_resolvable() -> bool:
     return preflight_which(GROK_BINARY_NAME) is not None
 
 
-def _is_claude_dev_env_config_present(role: str) -> bool:
+def _required_agent_filenames(role: str, agent: str | None) -> tuple[str, ...] | None:
+    if agent is not None:
+        return (f"{agent}{AGENT_DEFINITION_SUFFIX}",)
+    return ALL_AGENT_FILENAMES_BY_ROLE.get(role)
+
+
+def _is_claude_dev_env_config_present(role: str, agent: str | None = None) -> bool:
     if not _install_manifest_path().is_file():
         return False
     try:
         poteto_mode_skill_path()
     except OSError:
         return False
-    all_agent_filenames = ALL_AGENT_FILENAMES_BY_ROLE.get(role)
+    all_agent_filenames = _required_agent_filenames(role, agent)
     if all_agent_filenames is None:
         return False
     agents_root = _agents_directory()
@@ -390,6 +398,7 @@ def run_preflight(
     role: str,
     should_ping: bool,
     run_state_directory: Path,
+    agent: str | None = None,
 ) -> PreflightOutcome:
     """Evaluate whether tier 1 (grok headless) is usable.
 
@@ -398,6 +407,9 @@ def run_preflight(
         should_ping: When True, run the opt-in cached live single-turn ping.
         run_state_directory: Run-scoped directory for leader sockets and cache.
             Best-effort mkdir when missing; callers need not create it first.
+        agent: The agent definition stem a caller names for its own role.
+            When set, that one definition file must be installed in place of
+            the role's registered set.
 
     Returns:
         The soft-gate outcome. Callers treat a non-usable outcome as fallthrough,
@@ -412,7 +424,7 @@ def run_preflight(
     auth_outcome = _probe_grok_auth(run_state_directory)
     if not auth_outcome.is_usable:
         return auth_outcome
-    if not _is_claude_dev_env_config_present(role):
+    if not _is_claude_dev_env_config_present(role, agent):
         return _fallthrough(REASON_CLAUDE_DEV_ENV_CONFIG_MISSING)
     if should_ping:
         return _probe_grok_ping(run_state_directory)

package/scripts/resolve_worker_spawn.py

@@ -15,9 +15,9 @@ Walk order:
 
 Import ``resolve_worker_spawn`` for the outcome object, or run as a CLI::
 
-    python resolve_worker_spawn.py --role <role> --prompt-file <path>
-        --cwd <dir> --timeout-seconds N --run-temp-dir <dir>
-        [--enable-claude-tier]
+    python resolve_worker_spawn.py --role <role> [--agent <stem>]
+        --prompt-file <path> --cwd <dir> --timeout-seconds N
+        --run-temp-dir <dir> [--enable-claude-tier]
 """
 
 from __future__ import annotations
@@ -72,6 +72,7 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     ATTEMPT_KEY_OK,
     ATTEMPT_KEY_REASON,
     ATTEMPT_KEY_TIER,
+    CLI_AGENT_FLAG,
     CLI_ENABLE_CLAUDE_TIER_FLAG,
     CLI_ROLE_FLAG,
     CLI_RUN_STATE_DIR_FLAG,
@@ -284,13 +285,12 @@ def _served_claude_outcome(
 
 def _run_tier_claude_headless(
     *,
-    role: str,
+    agent_name: str,
     prompt_file: Path,
     working_directory: Path,
     timeout_seconds: int,
     all_attempts: list[SpawnAttempt],
 ) -> SpawnOutcome:
-    agent_name = _primary_agent_name_for_role(role)
     all_claude_arguments = _build_claude_arguments(agent_name=agent_name)
     try:
         prompt_stdin = prompt_file.open(encoding=UTF8_ENCODING)
@@ -310,7 +310,7 @@ def _run_tier_claude_headless(
 
 def _after_grok_fallthrough(
     *,
-    role: str,
+    agent_name: str,
     prompt_file: Path,
     working_directory: Path,
     timeout_seconds: int,
@@ -325,7 +325,7 @@ def _after_grok_fallthrough(
             all_attempts, returncode=fallthrough_returncode
         )
     return _run_tier_claude_headless(
-        role=role,
+        agent_name=agent_name,
         prompt_file=prompt_file,
         working_directory=working_directory,
         timeout_seconds=timeout_seconds,
@@ -335,13 +335,12 @@ def _after_grok_fallthrough(
 
 def _run_tier_grok(
     *,
-    role: str,
+    agent_name: str,
     prompt_file: Path,
     working_directory: Path,
     run_state_directory: Path,
     timeout_seconds: int,
 ) -> GrokRunnerOutcome:
-    agent_name = _primary_agent_name_for_role(role)
     return spawn_grok_runner(
         prompt_file=prompt_file,
         working_directory=working_directory,
@@ -354,7 +353,7 @@ def _run_tier_grok(
 def _record_preflight_fallthrough(
     preflight_outcome: PreflightOutcome,
     *,
-    role: str,
+    agent_name: str,
     prompt_file: Path,
     working_directory: Path,
     timeout_seconds: int,
@@ -362,7 +361,7 @@ def _record_preflight_fallthrough(
 ) -> SpawnOutcome:
     all_attempts = [_attempt(TIER_GROK, is_ok=False, reason=preflight_outcome.reason)]
     return _after_grok_fallthrough(
-        role=role,
+        agent_name=agent_name,
         prompt_file=prompt_file,
         working_directory=working_directory,
         timeout_seconds=timeout_seconds,
@@ -387,7 +386,7 @@ def _record_grok_success(
 def _record_grok_fallthrough(
     grok_outcome: GrokRunnerOutcome,
     *,
-    role: str,
+    agent_name: str,
     prompt_file: Path,
     working_directory: Path,
     timeout_seconds: int,
@@ -401,7 +400,7 @@ def _record_grok_fallthrough(
         )
     ]
     return _after_grok_fallthrough(
-        role=role,
+        agent_name=agent_name,
         prompt_file=prompt_file,
         working_directory=working_directory,
         timeout_seconds=timeout_seconds,
@@ -419,6 +418,7 @@ def resolve_worker_spawn(
     timeout_seconds: int,
     is_claude_tier_enabled: bool,
     run_state_directory: Path,
+    agent: str | None = None,
 ) -> SpawnOutcome:
     """Walk the worker-spawn tiers and return the structured outcome.
 
@@ -433,6 +433,9 @@ def resolve_worker_spawn(
         timeout_seconds: Timeout applied to each tier invocation.
         is_claude_tier_enabled: When True, allow tier 3 on a Claude host.
         run_state_directory: Run-scoped directory for leader sockets and cache.
+        agent: The agent definition stem that serves ``role``, named by a
+            caller whose role this package does not register. None maps
+            ``role`` through the package's own role table.
 
     Returns:
         The dispatcher outcome including the ordered attempts trail.
@@ -443,15 +446,17 @@ def resolve_worker_spawn(
             config-error exit code.
     """
     require_timeout_within_bounds(timeout_seconds)
+    agent_name = agent or _primary_agent_name_for_role(role)
     preflight_outcome: PreflightOutcome = spawn_preflight_runner(
         role=role,
         should_ping=False,
         run_state_directory=run_state_directory,
+        agent=agent,
     )
     if not preflight_outcome.is_usable:
         return _record_preflight_fallthrough(
             preflight_outcome,
-            role=role,
+            agent_name=agent_name,
             prompt_file=prompt_file,
             working_directory=working_directory,
             timeout_seconds=timeout_seconds,
@@ -459,7 +464,7 @@ def resolve_worker_spawn(
         )
 
     grok_outcome = _run_tier_grok(
-        role=role,
+        agent_name=agent_name,
         prompt_file=prompt_file,
         working_directory=working_directory,
         run_state_directory=run_state_directory,
@@ -469,7 +474,7 @@ def resolve_worker_spawn(
         return _record_grok_success(grok_outcome)
     return _record_grok_fallthrough(
         grok_outcome,
-        role=role,
+        agent_name=agent_name,
         prompt_file=prompt_file,
         working_directory=working_directory,
         timeout_seconds=timeout_seconds,
@@ -512,6 +517,14 @@ def _build_argument_parser() -> argparse.ArgumentParser:
         default=DEFAULT_ROLE,
         help="Worker role name for preflight; mapped to a primary agent for grok.",
     )
+    parser.add_argument(
+        CLI_AGENT_FLAG,
+        default=None,
+        help=(
+            "Agent definition stem that serves the role, for a role this "
+            "package does not register."
+        ),
+    )
     parser.add_argument(
         PROMPT_FILE_FLAG,
         dest="prompt_file",
@@ -654,6 +667,7 @@ def main(all_command_arguments: list[str]) -> int:
             timeout_seconds=parsed_arguments.timeout_seconds,
             is_claude_tier_enabled=parsed_arguments.is_claude_tier_enabled,
             run_state_directory=run_state_directory,
+            agent=parsed_arguments.agent,
         )
     except WorkerTimeoutOutOfBoundsError as bounds_error:
         is_config_error = True

package/scripts/review_closure.py

@@ -26,6 +26,7 @@ from dev_env_scripts_constants.review_closure_constants import (
     DRIVER_LOGIN_ARGUMENT_HELP,
     ERROR_EXIT_CODE,
     FINDING_LINE_TEMPLATE,
+    NOTICE_MARKER_ARGUMENT_HELP,
     NUMBER_ARGUMENT_HELP,
     OPEN_EXIT_CODE,
     SLUG_ARGUMENT_HELP,
@@ -60,7 +61,7 @@ def build_parser() -> argparse.ArgumentParser:
 
     Returns:
         A parser taking a repository slug, a pull request number, and any
-        number of extra driver logins.
+        number of extra driver logins and notice markers.
     """
     parser = argparse.ArgumentParser(description=COMMAND_DESCRIPTION)
     parser.add_argument("slug", help=SLUG_ARGUMENT_HELP)
@@ -71,11 +72,21 @@ def build_parser() -> argparse.ArgumentParser:
         default=[],
         help=DRIVER_LOGIN_ARGUMENT_HELP,
     )
+    parser.add_argument(
+        "--notice-marker",
+        action="append",
+        default=[],
+        help=NOTICE_MARKER_ARGUMENT_HELP,
+    )
     return parser
 
 
 def closure_report(
-    slug: str, number: int, all_extra_logins: Sequence[str], token: str
+    slug: str,
+    number: int,
+    all_extra_logins: Sequence[str],
+    token: str,
+    all_extra_notice_markers: Sequence[str] = (),
 ) -> ClosureReport:
     """Read one pull request and judge the findings on its head.
 
@@ -85,6 +96,8 @@ def closure_report(
         all_extra_logins: Logins that count as the driving agent beside the
             account that opened the pull request.
         token: The GitHub token the reads authenticate with.
+        all_extra_notice_markers: Text that marks a bot comment as a notice on
+            this repository, beside the built-in markers.
 
     Returns:
         The verdict line and each finding that waits.
@@ -95,7 +108,7 @@ def closure_report(
     all_pull_request_fields = read_pull_request(slug, number, token)
     all_findings = all_open_findings(
         read_review_threads(slug, number, token),
-        read_top_level_comments(slug, number, token),
+        read_top_level_comments(slug, number, token, all_extra_notice_markers),
         driver_logins(all_pull_request_fields, all_extra_logins),
         read_approvals_conclusion(slug, head_sha(all_pull_request_fields), token),
     )
@@ -118,7 +131,11 @@ def main(all_arguments: Sequence[str]) -> int:
     parsed = build_parser().parse_args(all_arguments)
     try:
         report = closure_report(
-            parsed.slug, parsed.number, parsed.driver_login, github_token()
+            parsed.slug,
+            parsed.number,
+            parsed.driver_login,
+            github_token(),
+            parsed.notice_marker,
         )
     except GitHubError as failure:
         print(failure, file=sys.stderr)

package/scripts/review_closure_github.py

@@ -23,7 +23,7 @@ import json
 import os
 import urllib.error
 import urllib.request
-from collections.abc import Mapping
+from collections.abc import Mapping, Sequence
 
 from dev_env_scripts_constants.review_closure_constants import (
     ALL_THREAD_NODE_KEYS,
@@ -202,7 +202,10 @@ def read_review_comments_by_id(
 
 
 def read_top_level_comments(
-    slug: str, number: int, token: str
+    slug: str,
+    number: int,
+    token: str,
+    all_extra_notice_markers: Sequence[str] = (),
 ) -> tuple[TopLevelComment, ...]:
     """Read every top-level comment on a pull request.
 
@@ -210,6 +213,8 @@ def read_top_level_comments(
         slug: The repository as ``owner/name``.
         number: The pull request number.
         token: The GitHub token the request authenticates with.
+        all_extra_notice_markers: Markers the calling repository adds to the
+            built-in notice markers.
 
     Returns:
         Each comment posted on the pull request itself, outside any review
@@ -223,7 +228,7 @@ def read_top_level_comments(
         TOP_LEVEL_COMMENTS_ENDPOINT_TEMPLATE, slug, number, token
     )
     return tuple(
-        _parsed_top_level_comment(each_record)
+        _parsed_top_level_comment(each_record, all_extra_notice_markers)
         for each_record in all_records
         if isinstance(each_record, Mapping)
     )
@@ -231,9 +236,10 @@ def read_top_level_comments(
 
 def _parsed_top_level_comment(
     all_comment_fields: Mapping[str, object],
+    all_extra_notice_markers: Sequence[str],
 ) -> TopLevelComment:
     try:
-        return parse_top_level_comment(all_comment_fields)
+        return parse_top_level_comment(all_comment_fields, all_extra_notice_markers)
     except ValueError as failure:
         raise GitHubError(
             UNREADABLE_TOP_LEVEL_COMMENT_TEMPLATE.format(record=all_comment_fields)

package/scripts/review_closure_model.py

@@ -426,6 +426,7 @@ def comment_records_by_id(
 
 def parse_top_level_comment(
     all_comment_fields: Mapping[str, object],
+    all_extra_notice_markers: Sequence[str] = (),
 ) -> TopLevelComment:
     """Read one top-level comment from the REST answer.
 
@@ -434,6 +435,8 @@ def parse_top_level_comment(
 
     Args:
         all_comment_fields: The comment as the issue comments route reports it.
+        all_extra_notice_markers: Markers the calling repository adds to the
+            built-in ones.
 
     Returns:
         The comment in the shape the closure decision reads.
@@ -448,7 +451,10 @@ def parse_top_level_comment(
         author_login=_comment_author_login(all_comment_fields),
         is_bot=is_bot,
         is_notice=is_bot
-        and any(each_marker in body for each_marker in ALL_NOTICE_COMMENT_MARKERS),
+        and any(
+            each_marker in body
+            for each_marker in (*ALL_NOTICE_COMMENT_MARKERS, *all_extra_notice_markers)
+        ),
         created_at=datetime.fromisoformat(str(all_comment_fields.get(CREATED_AT_KEY))),
         updated_at=datetime.fromisoformat(str(all_comment_fields.get(UPDATED_AT_KEY))),
         url=str(all_comment_fields.get(HTML_URL_KEY) or ""),

package/scripts/test_grok_worker_preflight.py

@@ -1125,3 +1125,19 @@ def test_ping_incidental_credit_and_port_429_are_not_usage_exhaustion(
     assert outcome.is_usable is False
     assert outcome.reason == REASON_GROK_AUTH_FAILED
     assert outcome.reason != REASON_GROK_USAGE_EXHAUSTED
+
+
+def test_caller_named_agent_needs_its_own_definition_file(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    _write_install_layout(tmp_path)
+    monkeypatch.setattr(preflight, "claude_config_home", lambda: tmp_path)
+
+    assert not preflight._is_claude_dev_env_config_present("vendor-role")
+    assert not preflight._is_claude_dev_env_config_present(
+        "vendor-role", "vendor-agent"
+    )
+    (tmp_path / AGENTS_SUBDIRECTORY / "vendor-agent.md").write_text(
+        "# vendor-agent\n", encoding=UTF8_ENCODING
+    )
+    assert preflight._is_claude_dev_env_config_present("vendor-role", "vendor-agent")

package/scripts/test_resolve_worker_spawn.py

@@ -32,6 +32,7 @@ from dev_env_scripts_constants.claude_chain_constants import (  # noqa: E402
 )
 from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     AGENT_FLAG,
+    CLI_AGENT_FLAG,
     ALL_AGENT_FILENAMES_BY_ROLE,
     ATTEMPT_KEY_OK,
     ATTEMPT_KEY_REASON,
@@ -1328,3 +1329,49 @@ def test_usage_limit_fallover_delivers_full_prompt_to_each_binary(
     assert prompt_text_by_command["claude-profile-c"] == FIXTURE_PROMPT_TEXT
     assert outcome.tier_used == TIER_CLAUDE_HEADLESS
     assert outcome.is_ok is True
+
+
+def test_caller_named_agent_serves_an_unregistered_role(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    prompt_file, working_directory, run_state_directory = _paths(tmp_path)
+    call_log = _install_seams(
+        monkeypatch,
+        grok_outcome=_grok_failure(CLASSIFICATION_AUTH_FAILURE),
+        claude_outcome=_claude_served(),
+        host_profile=HOST_PROFILE_CLAUDE,
+    )
+    all_preflight_keyword_arguments: list[dict[str, object]] = []
+
+    def recording_preflight(**keyword_arguments: object) -> PreflightOutcome:
+        all_preflight_keyword_arguments.append(dict(keyword_arguments))
+        return _usable_preflight()
+
+    monkeypatch.setattr(dispatcher, "spawn_preflight_runner", recording_preflight)
+
+    exit_code = dispatcher.main(
+        [
+            CLI_ROLE_FLAG,
+            "vendor-role",
+            CLI_AGENT_FLAG,
+            "vendor-agent",
+            PROMPT_FILE_FLAG,
+            str(prompt_file),
+            CWD_FLAG,
+            str(working_directory),
+            CLI_RUN_STATE_DIR_FLAG,
+            str(run_state_directory),
+            CLI_ENABLE_CLAUDE_TIER_FLAG,
+        ]
+    )
+    capsys.readouterr()
+
+    assert exit_code == 0
+    assert all_preflight_keyword_arguments[0]["agent"] == "vendor-agent"
+    assert call_log.grok_keyword_arguments is not None
+    assert call_log.grok_keyword_arguments["agent_name"] == "vendor-agent"
+    assert call_log.claude_arguments is not None
+    agent_flag_index = call_log.claude_arguments.index(AGENT_FLAG)
+    assert call_log.claude_arguments[agent_flag_index + 1] == "vendor-agent"

package/scripts/tests/test_review_closure.py

@@ -151,3 +151,25 @@ def should_print_the_url_of_a_waiting_top_level_comment(
 
     assert status == 1
     assert summary_url in capsys.readouterr().out
+
+
+def should_pass_each_notice_marker_to_the_top_level_comment_read(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    stub_reads(monkeypatch, (answered_thread(),))
+    all_received_markers: list[list[str]] = []
+
+    def read_comments(
+        slug: str, number: int, token: str, all_extra_notice_markers: list[str]
+    ) -> tuple[model.TopLevelComment, ...]:
+        all_received_markers.append(all_extra_notice_markers)
+        return ()
+
+    monkeypatch.setattr(command, "read_top_level_comments", read_comments)
+
+    status = command.main(
+        [SLUG, "7", "--notice-marker", "<!-- a -->", "--notice-marker", "<!-- b -->"]
+    )
+
+    assert status == 0
+    assert all_received_markers == [["<!-- a -->", "<!-- b -->"]]

package/scripts/tests/test_review_closure_github.py

@@ -289,3 +289,23 @@ def should_report_a_top_level_comment_without_timestamps(
 
     with pytest.raises(GitHubError):
         reader.read_top_level_comments("jl-cmd/claude-dev-env", 7, TOKEN)
+
+
+def should_read_a_bot_comment_carrying_a_passed_marker_as_a_notice(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    notice_record = {
+        **top_level_record(1),
+        "user": {"login": "qodo-code-review[bot]", "type": "Bot"},
+        "body": "<!-- vendor:trial-expiring -->\n\nYour trial ends soon.",
+    }
+    answer_with(
+        monkeypatch,
+        {"issues/7/comments?per_page=100&page=1": (200, [notice_record])},
+    )
+
+    all_comments = reader.read_top_level_comments(
+        "jl-cmd/claude-dev-env", 7, TOKEN, ("<!-- vendor:trial-expiring -->",)
+    )
+
+    assert [each.is_notice for each in all_comments] == [True]

package/scripts/tests/test_review_closure_model.py

@@ -549,3 +549,21 @@ def should_read_a_person_top_level_comment_record() -> None:
     )
 
     assert comment == top_level_comment(REVIEWER, 1, edited_minute=5, is_bot=False)
+
+
+def should_read_a_bot_comment_carrying_a_repository_marker_as_a_notice() -> None:
+    body = "<!-- vendor:trial-expiring -->\n\nYour trial ends soon."
+
+    assert not model.parse_top_level_comment(notice_record(body, "Bot")).is_notice
+    assert model.parse_top_level_comment(
+        notice_record(body, "Bot"), ("<!-- vendor:trial-expiring -->",)
+    ).is_notice
+
+
+def should_read_a_person_carrying_a_repository_marker_as_a_comment() -> None:
+    comment = model.parse_top_level_comment(
+        notice_record("<!-- vendor:trial-expiring -->", "User"),
+        ("<!-- vendor:trial-expiring -->",),
+    )
+
+    assert not comment.is_notice