claude-dev-env 8.40.1 → 8.42.0

package/docs/rule-guides/destructive-commands.md

@@ -32,7 +32,7 @@ A file left in the OS temp directory or under `$CLAUDE_JOB_DIR` is cleaned by th
 
 The permission matcher reads the raw command string. A destructive literal carried only as data still sits in that string, so it can push the command out of an allowed shape and into a prompt even though the shell never executes it. This covers a commit message, a PR or issue body, an echoed string, a `python -c` or `node -e` or `awk` argument, and a heredoc.
 
-- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [`gh-cli-conventions.md`](../../rules/gh-cli-conventions.md). Never `git commit -m` or `gh … -b`.
+- Bodies that describe destructive-command behavior go in a file passed by path, such as `git commit -F <file>` or `gh … --body-file <file>`. See [gh CLI conventions](../../.agents/skills/pr-lifecycle/SKILL.md#gh-cli-conventions). Never `git commit -m` or `gh … -b`.
 - To exercise or verify a hook, run the committed test suite with `python -m pytest <test_file>`, which passes the command strings as in-language data. Never an inline `python -c` harness.
 
 ## Every subagent prompt carries the rule

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -0,0 +1,190 @@
+"""Deny pull request lifecycle actions until their skill appears in the transcript."""
+
+from __future__ import annotations
+
+import json
+import re
+import shlex
+import sys
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.pr_lifecycle_skill_gate_constants import (
+    ALL_API_ACTION_NAMES,
+    ALL_COMMAND_PREFIX_WORDS,
+    ALL_GITHUB_MCP_TOOL_SUFFIXES,
+    ALL_PREFIX_OPTIONS_WITH_VALUE,
+    ALL_SLASH_COMMAND_MARKERS,
+    ALL_TRANSCRIPT_PATH_FIELDS,
+    COMMAND_SEPARATORS,
+    COMMAND_WHITESPACE,
+    DENY_DECISION,
+    DENY_REASON,
+    ENVIRONMENT_ASSIGNMENT_PATTERN,
+    GH_API_COMMAND,
+    GH_OPTIONS_WITH_VALUE,
+    GH_PULL_REQUEST_COMMAND,
+    GIT_ACTIONS,
+    GIT_GLOBAL_OPTIONS_WITH_VALUE,
+    HOOK_EVENT_NAME,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+    MERGE_PATH_SUFFIX,
+    OPTION_AND_VALUE_WORD_COUNT,
+    PERMISSION_DECISION_KEY,
+    PERMISSION_DECISION_REASON_KEY,
+    SHELL_TOOL_NAMES,
+    SKILL_NAME,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from transcript_skill_scan import is_skill_loaded_after_last_compaction
+
+
+def _command_segments(command: str) -> list[list[str]]:
+    lexer = shlex.shlex(command, posix=True, punctuation_chars=COMMAND_SEPARATORS)
+    lexer.whitespace = COMMAND_WHITESPACE
+    lexer.whitespace_split = True
+    all_segments: list[list[str]] = []
+    each_segment: list[str] = []
+    try:
+        all_words = list(lexer)
+    except ValueError:
+        return []
+    for each_word in all_words:
+        if each_word[0] in COMMAND_SEPARATORS:
+            all_segments.append(each_segment)
+            each_segment = []
+            continue
+        each_segment.append(each_word)
+    if each_segment:
+        all_segments.append(each_segment)
+    return [each_group for each_group in all_segments if each_group]
+
+
+def _next_command_word(
+    all_words: list[str], start: int, all_options_with_value: frozenset[str]
+) -> tuple[str | None, int]:
+    index = start
+    while index < len(all_words):
+        each_word = all_words[index]
+        if each_word in all_options_with_value:
+            index += OPTION_AND_VALUE_WORD_COUNT
+            continue
+        if each_word.startswith("-"):
+            index += 1
+            continue
+        return each_word, index + 1
+    return None, index
+
+
+def _is_git_action(all_words: list[str]) -> bool:
+    action, _ = _next_command_word(all_words, 1, GIT_GLOBAL_OPTIONS_WITH_VALUE)
+    return action in GIT_ACTIONS
+
+
+def _is_gh_action(all_words: list[str]) -> bool:
+    action, next_index = _next_command_word(all_words, 1, GH_OPTIONS_WITH_VALUE)
+    if action == GH_PULL_REQUEST_COMMAND:
+        subcommand, _ = _next_command_word(all_words, next_index, GH_OPTIONS_WITH_VALUE)
+        return subcommand is not None
+    if action != GH_API_COMMAND:
+        return False
+    all_api_arguments = all_words[next_index:]
+    if any(each_name in each_word for each_word in all_api_arguments for each_name in ALL_API_ACTION_NAMES):
+        return True
+    return any(
+        each_word.split("?", 1)[0].rstrip("/").endswith(MERGE_PATH_SUFFIX)
+        for each_word in all_api_arguments
+    )
+
+
+def _words_from_executable(all_words: list[str]) -> list[str]:
+    index = 0
+    while index < len(all_words):
+        each_word = all_words[index]
+        if re.match(ENVIRONMENT_ASSIGNMENT_PATTERN, each_word):
+            index += 1
+            continue
+        if each_word not in ALL_COMMAND_PREFIX_WORDS:
+            return all_words[index:]
+        index += 1
+        while index < len(all_words) and all_words[index].startswith("-"):
+            is_valued = all_words[index] in ALL_PREFIX_OPTIONS_WITH_VALUE
+            index += OPTION_AND_VALUE_WORD_COUNT if is_valued else 1
+    return []
+
+
+def _matches_shell_command(command: str) -> bool:
+    for each_segment in _command_segments(command):
+        all_command_words = _words_from_executable(each_segment)
+        if not all_command_words:
+            continue
+        executable = all_command_words[0].lower()
+        if executable in {"git", "git.exe"} and _is_git_action(all_command_words):
+            return True
+        if executable in {"gh", "gh.exe"} and _is_gh_action(all_command_words):
+            return True
+    return False
+
+
+def _is_governed_action(all_payload_fields: dict[str, object]) -> bool:
+    tool_name = all_payload_fields.get("tool_name")
+    if not isinstance(tool_name, str):
+        return False
+    if tool_name.endswith(ALL_GITHUB_MCP_TOOL_SUFFIXES):
+        return True
+    if tool_name not in SHELL_TOOL_NAMES:
+        return False
+    tool_input = all_payload_fields.get("tool_input")
+    return isinstance(tool_input, dict) and isinstance(tool_input.get("command"), str) and _matches_shell_command(tool_input["command"])
+
+
+def _transcript_load_status(path: str) -> bool | None:
+    try:
+        with open(path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY) as transcript:
+            return is_skill_loaded_after_last_compaction(
+                transcript, (SKILL_NAME,), ALL_SLASH_COMMAND_MARKERS
+            )
+    except OSError:
+        return None
+
+
+def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return a deny for a governed action with readable, unloaded transcripts.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    if not _is_governed_action(all_payload_fields):
+        return None
+    paths = [all_payload_fields.get(field) for field in ALL_TRANSCRIPT_PATH_FIELDS]
+    readable_paths = [path for path in paths if isinstance(path, str) and path]
+    if not readable_paths:
+        return None
+    statuses = [_transcript_load_status(path) for path in readable_paths]
+    if any(status is None or status for status in statuses):
+        return None
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            "hookEventName": HOOK_EVENT_NAME,
+            PERMISSION_DECISION_KEY: DENY_DECISION,
+            PERMISSION_DECISION_REASON_KEY: DENY_REASON,
+        }
+    }
+
+
+def main() -> int:
+    """Read one payload, print a deny when needed, and exit zero."""
+    payload = read_hook_input_dictionary_from_stdin()
+    if payload is not None:
+        decision = decision_for(payload)
+        if decision is not None:
+            sys.stdout.write(json.dumps(decision) + "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -0,0 +1,163 @@
+"""Behavior tests for the pull request lifecycle PreToolUse gate."""
+
+import json
+import sys
+from io import BytesIO, StringIO, TextIOWrapper
+from pathlib import Path
+from unittest.mock import patch
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from blocking import pr_lifecycle_skill_gate as gate
+from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
+
+
+def _transcript(tmp_path: Path, skill_name: str | None = None, compact: bool = False) -> Path:
+    lines = [json.dumps({"type": "user", "message": {"content": "Start."}})]
+    if skill_name:
+        lines.append(json.dumps({"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": skill_name}}]}}))
+    if compact:
+        lines.append(json.dumps({"subtype": "compact_boundary"}))
+    transcript_path = tmp_path / "session.jsonl"
+    transcript_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return transcript_path
+
+
+def _payload(command: str, path: Path, tool_name: str = "Bash") -> dict[str, object]:
+    return {"tool_name": tool_name, "tool_input": {"command": command}, "transcript_path": str(path)}
+
+
+def _run_main(payload: object) -> tuple[int, str]:
+    stdin_text = payload if isinstance(payload, str) else json.dumps(payload)
+    output = StringIO()
+    input_stream = TextIOWrapper(BytesIO(stdin_text.encode("utf-8")), encoding="utf-8")
+    with patch("sys.stdin", input_stream), patch("sys.stdout", output):
+        exit_code = gate.main()
+    return exit_code, output.getvalue()
+
+
+def _assert_denied(payload: dict[str, object]) -> None:
+    assert gate.decision_for(payload) == {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": DENY_REASON,
+        }
+    }
+
+
+def test_unloaded_pull_request_command_is_denied(tmp_path: Path) -> None:
+    exit_code, output = _run_main(_payload("gh pr create", _transcript(tmp_path)))
+    assert exit_code == 0
+    decision = json.loads(output)["hookSpecificOutput"]
+    assert decision["hookEventName"] == "PreToolUse"
+    assert decision["permissionDecision"] == "deny"
+    assert "Skill tool" in decision["permissionDecisionReason"]
+    assert "same command again" in decision["permissionDecisionReason"]
+
+
+def test_loaded_skill_allows_action_silently(tmp_path: Path) -> None:
+    path = _transcript(tmp_path, "plugin:pr-lifecycle")
+    assert _run_main(_payload("gh pr create", path)) == (0, "")
+
+
+def test_user_slash_command_loads_skill(tmp_path: Path) -> None:
+    path = tmp_path / "slash.jsonl"
+    path.write_text(json.dumps({"type": "user", "message": {"content": "<command-name>/pr-lifecycle</command-name>"}}) + "\n", encoding="utf-8")
+    assert _run_main(_payload("git commit", path)) == (0, "")
+
+
+def test_compaction_requires_another_invocation(tmp_path: Path) -> None:
+    _assert_denied(_payload("git push", _transcript(tmp_path, "pr-lifecycle", compact=True)))
+
+
+def test_agent_transcript_can_supply_invocation(tmp_path: Path) -> None:
+    session_path = _transcript(tmp_path)
+    agent_path = tmp_path / "agent.jsonl"
+    agent_path.write_text(json.dumps({"type": "assistant", "message": {"content": [{"type": "tool_use", "name": "Skill", "input": {"skill": "pr-lifecycle"}}]}}) + "\n", encoding="utf-8")
+    payload = _payload("git push", session_path)
+    payload["agent_transcript_path"] = str(agent_path)
+    assert gate.decision_for(payload) is None
+
+
+def test_unreadable_or_missing_transcript_allows_silently(tmp_path: Path) -> None:
+    payload = _payload("gh pr create", tmp_path / "missing.jsonl")
+    assert _run_main(payload) == (0, "")
+    payload.pop("transcript_path")
+    assert _run_main(payload) == (0, "")
+
+
+def test_action_command_shapes(tmp_path: Path) -> None:
+    path = _transcript(tmp_path)
+    commands = (
+        "git commit",
+        "git -C some/path commit -F message.txt",
+        "git --git-dir=.git push origin head",
+        "gh pr create",
+        "gh -R owner/repo pr --repo owner/repo merge",
+        "gh api -X PUT repos/owner/repo/pulls/1/merge",
+        "gh api graphql -f query='mutation { enablePullRequestAutoMerge }'",
+        "gh api graphql -f name=auto-merge",
+        "echo done; gh pr edit",
+        "GIT_TRACE=1 git push",
+        "env -u GH_TOKEN gh pr merge 1",
+        "env --unset=GH_TOKEN GH_HOST=github.com gh pr create",
+        "sudo git push",
+        "(git push)",
+    )
+    for command in commands:
+        _assert_denied(_payload(command, path, "PowerShell"))
+
+
+def test_non_action_command_shapes(tmp_path: Path) -> None:
+    path = _transcript(tmp_path)
+    commands = (
+        "git status",
+        "git commit-tree 123",
+        "git log --grep push",
+        "echo 'gh pr create'",
+        "gh api repos/owner/repo/pulls/1/mergeability",
+        "gh issue create --body-file message.txt",
+        "gh pr",
+        "GH_TOKEN=x gh issue list",
+        "env -u GH_TOKEN git status",
+    )
+    for command in commands:
+        assert gate.decision_for(_payload(command, path)) is None, command
+
+
+def test_matching_github_mcp_tools_are_denied(tmp_path: Path) -> None:
+    path = _transcript(tmp_path)
+    for suffix in ("create_pull_request", "merge_pull_request", "enable_pr_auto_merge", "update_pull_request"):
+        payload = _payload("", path, "mcp__github__" + suffix)
+        _assert_denied(payload)
+
+
+def test_malformed_payload_exits_zero_silently() -> None:
+    assert _run_main("bad json") == (0, "")
+
+
+def test_hook_has_its_own_pre_tool_use_registration() -> None:
+    registration_path = HOOKS_DIRECTORY / "hooks.json"
+    all_registration_fields = json.loads(registration_path.read_text(encoding="utf-8"))
+    all_groups = all_registration_fields["hooks"]["PreToolUse"]
+    matching_groups = [
+        each_group
+        for each_group in all_groups
+        if each_group["matcher"]
+        == "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)"
+    ]
+    assert matching_groups == [
+        {
+            "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_lifecycle_skill_gate.py",
+                    "timeout": 10,
+                }
+            ],
+        }
+    ]

package/hooks/hooks.json

@@ -24,6 +24,21 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/routing/subagent_model_routing.mjs\"",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "Workflow|mcp__github__actions_run_trigger",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -47,6 +62,16 @@
           }
         ]
       },
+      {
+        "matcher": "Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request)",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pr_lifecycle_skill_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "EnterWorktree",
         "hooks": [

package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py

@@ -0,0 +1,33 @@
+"""Constants for the pull request lifecycle skill gate."""
+
+HOOK_EVENT_NAME = "PreToolUse"
+HOOK_SPECIFIC_OUTPUT_KEY = "hookSpecificOutput"
+PERMISSION_DECISION_KEY = "permissionDecision"
+PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
+DENY_DECISION = "deny"
+DENY_REASON = (
+    "Invoke the pr-lifecycle skill with the Skill tool, then run the same command again."
+)
+SKILL_NAME = "pr-lifecycle"
+ALL_SLASH_COMMAND_MARKERS = ("<command-name>/pr-lifecycle</command-name>",)
+SHELL_TOOL_NAMES = frozenset({"Bash", "PowerShell"})
+ALL_GITHUB_MCP_TOOL_SUFFIXES = (
+    "__create_pull_request",
+    "__merge_pull_request",
+    "__enable_pr_auto_merge",
+    "__update_pull_request",
+)
+ALL_TRANSCRIPT_PATH_FIELDS = ("transcript_path", "agent_transcript_path")
+COMMAND_SEPARATORS = ";|&\n()"
+COMMAND_WHITESPACE = " \t\r"
+OPTION_AND_VALUE_WORD_COUNT = 2
+GIT_GLOBAL_OPTIONS_WITH_VALUE = frozenset({"-C", "-c", "--git-dir", "--work-tree", "--namespace", "--config-env"})
+GH_OPTIONS_WITH_VALUE = frozenset({"-R", "--repo", "--hostname", "--config", "-H", "--header", "-X", "--method", "-F", "--field", "-f", "--raw-field", "--input", "--jq", "-q", "--template", "-t", "--cache"})
+GIT_ACTIONS = frozenset({"commit", "push"})
+GH_PULL_REQUEST_COMMAND = "pr"
+GH_API_COMMAND = "api"
+MERGE_PATH_SUFFIX = "/merge"
+ALL_API_ACTION_NAMES = ("auto-merge", "enablePullRequestAutoMerge")
+ALL_COMMAND_PREFIX_WORDS = frozenset({"env", "sudo", "command", "exec", "nohup", "time"})
+ALL_PREFIX_OPTIONS_WITH_VALUE = frozenset({"-u", "--unset", "-C", "--chdir", "-g", "--group", "--user"})
+ENVIRONMENT_ASSIGNMENT_PATTERN = r"^[A-Za-z_][A-Za-z0-9_]*="

package/hooks/hooks_constants/skill_loaded_reminder_constants.py

@@ -4,8 +4,6 @@ from __future__ import annotations
 
 __all__ = [
     "ALL_SELF_LOADING_SUBAGENT_TYPES",
-    "ASSISTANT_ENTRY_TYPE",
-    "COMPACT_BOUNDARY_SUBTYPE",
     "COMPACTION_REMINDER",
     "COMPACTION_SOURCE",
     "NOT_LOADED_REMINDER",
@@ -13,14 +11,11 @@ __all__ = [
     "PRE_TOOL_USE_EVENT_NAME",
     "PROMPT_SEPARATOR",
     "SESSION_START_EVENT_NAME",
-    "SKILL_TOOL_NAME",
     "ALL_SLASH_COMMAND_MARKERS",
     "SUBAGENT_START_EVENT_NAME",
     "CLAUDE_SUBAGENT_PROMPT_PREFIX",
     "CODEX_SUBAGENT_PROMPT_PREFIX",
     "ALL_SPAWN_PROMPT_FIELDS_AND_PREFIXES_BY_TOOL_NAME",
-    "TOOL_USE_BLOCK_TYPE",
-    "USER_ENTRY_TYPE",
     "USER_PROMPT_SUBMIT_EVENT_NAME",
     "WORKFLOW_SUBAGENT_TYPE",
 ]
@@ -42,11 +37,6 @@ ALL_SLASH_COMMAND_MARKERS = (
 )
 PROMPT_SEPARATOR = "\n\n"
 
-ASSISTANT_ENTRY_TYPE = "assistant"
-USER_ENTRY_TYPE = "user"
-TOOL_USE_BLOCK_TYPE = "tool_use"
-COMPACT_BOUNDARY_SUBTYPE = "compact_boundary"
-
 CLAUDE_SUBAGENT_PROMPT_PREFIX = (
     "Before any other work, invoke the poteto-mode skill with the Skill tool. "
     "Every prompt you write for a subagent opens with the same instruction."

package/hooks/hooks_constants/spawn_readiness_hook_constants.py

@@ -2,7 +2,7 @@
 
 Groups: the spawn tools it checks and their brief fields, the transcript entry
 shapes it reads, the tool names that count as a read or a question, the
-scope-settled line, and the deny messages and log fields.
+scope-settled line, and the reminder messages and log fields.
 """
 
 from __future__ import annotations
@@ -15,11 +15,22 @@ AGENT_ID_KEY = "agent_id"
 SUBAGENT_TYPE_INPUT_KEY = "subagent_type"
 
 THREAD_SPAWN_TOOL_NAME = "mcp__hearthbot__start_thread_session"
+CODEX_SPAWN_TOOL_NAME = "multi_agent_v1__spawn_agent"
+WORKFLOW_TOOL_NAME = "Workflow"
+WORKFLOW_SCRIPT_PATH_INPUT_KEY = "scriptPath"
 ALL_BRIEF_FIELDS_BY_SPAWN_TOOL_NAME = {
     "Agent": "prompt",
     "Task": "prompt",
     THREAD_SPAWN_TOOL_NAME: "instructions",
+    CODEX_SPAWN_TOOL_NAME: "message",
+    WORKFLOW_TOOL_NAME: "script",
 }
+WORKFLOW_DISPATCH_TOOL_NAME = "mcp__github__actions_run_trigger"
+DISPATCH_METHOD_INPUT_KEY = "method"
+DISPATCH_RUN_WORKFLOW_METHOD = "run_workflow"
+DISPATCH_INPUTS_KEY = "inputs"
+DISPATCH_PROMPT_INPUT_KEY = "prompt"
+CODEX_TURN_ID_KEY = "turn_id"
 ALL_READ_ONLY_SUBAGENT_TYPES = frozenset({"Explore", "Plan", "claude-code-guide"})
 
 ENTRY_TYPE_KEY = "type"
@@ -80,20 +91,26 @@ SCOPE_SETTLED_PREFIX = "Scope settled:"
 PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
 HOOK_SPECIFIC_OUTPUT_KEY = "hookSpecificOutput"
 HOOK_EVENT_NAME_KEY = "hookEventName"
-PERMISSION_DECISION_KEY = "permissionDecision"
-PERMISSION_DECISION_REASON_KEY = "permissionDecisionReason"
-PERMISSION_DENY = "deny"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
 MISSING_INVESTIGATION_REASON = (
-    "Investigate the request before this spawn. Read the files, threads, or "
-    "sources it names, so the brief and the agent count fit the task. Run the "
-    "reads in a message before the spawn."
+    "This spawn comes before any read of the request. Read the files, threads, "
+    "or sources the request names, then check that the brief and the agent "
+    "count fit the task."
 )
 MISSING_INTERVIEW_REASON = (
-    "Interview the user before this spawn. Ask your scope, requirements, and "
-    "goals questions through AskUserQuestion, a decision card, or an "
-    "interactive widget, and spawn after the answer. When the request "
-    "already settles scope, add a brief line that starts with "
-    f'"{SCOPE_SETTLED_PREFIX}" and names the reason.'
+    "This spawn comes before an answered question to the user. Ask the open "
+    "scope, requirements, and goals questions through AskUserQuestion, a "
+    "decision card, or an interactive widget. When the request already "
+    "settles scope, add a brief line that starts with "
+    f'"{SCOPE_SETTLED_PREFIX}" and names the defaults you chose.'
+)
+CODEX_TRANSCRIPT_REMINDER = (
+    "This hook reads no Codex transcript, because Codex documents that format "
+    "as unstable for hooks. Before this spawn, read what the request names, "
+    "size the agents to the independent pieces, and ask the user the open "
+    "scope questions. When the request already settles scope, add a brief "
+    f'line that starts with "{SCOPE_SETTLED_PREFIX}" and names the defaults '
+    "you chose."
 )
 REASON_SEPARATOR = " "
 
@@ -108,4 +125,5 @@ LOG_TOOL_USE_ID_KEY = "tool_use_id"
 LOG_OUTCOME_KEY = "outcome"
 LOG_SCOPE_SETTLED_LINE_KEY = "scope_settled_line"
 OUTCOME_SCOPE_SETTLED = "scope_settled"
+OUTCOME_REMINDED = "reminded"
 OUTCOME_TRANSCRIPT_UNREADABLE = "transcript_unreadable"

package/hooks/hooks_constants/test_pr_lifecycle_skill_gate_constants.py

@@ -0,0 +1,12 @@
+from hooks_constants import pr_lifecycle_skill_gate_constants as constants
+
+
+def test_gate_targets_the_named_skill_and_pre_tool_use() -> None:
+    assert constants.SKILL_NAME == "pr-lifecycle"
+    assert constants.HOOK_EVENT_NAME == "PreToolUse"
+    assert constants.DENY_DECISION == "deny"
+
+
+def test_gate_covers_shells_and_pull_request_tools() -> None:
+    assert constants.SHELL_TOOL_NAMES == {"Bash", "PowerShell"}
+    assert len(constants.ALL_GITHUB_MCP_TOOL_SUFFIXES) == 4

package/hooks/hooks_constants/test_transcript_skill_scan_constants.py

@@ -0,0 +1,7 @@
+from hooks_constants import transcript_skill_scan_constants as constants
+
+
+def test_transcript_entry_names() -> None:
+    assert constants.COMPACT_BOUNDARY_SUBTYPE == "compact_boundary"
+    assert constants.SKILL_TOOL_NAME == "Skill"
+    assert constants.TOOL_USE_BLOCK_TYPE == "tool_use"

package/hooks/hooks_constants/transcript_skill_scan_constants.py

@@ -0,0 +1,7 @@
+"""Entry fields used by transcript skill scans."""
+
+ASSISTANT_ENTRY_TYPE = "assistant"
+COMPACT_BOUNDARY_SUBTYPE = "compact_boundary"
+SKILL_TOOL_NAME = "Skill"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+USER_ENTRY_TYPE = "user"