claude-dev-env 8.59.0 → 8.61.0

package/.agents/skills/orchestrator/SKILL.md

@@ -3,8 +3,9 @@ name: orchestrator
 description: >-
   Coordinate user goals, parent tasks, workers, evidence, and recovery.
   Triggers: /orchestrator, orchestrate, operate like a coordinator,
-  track my goals, coordinate workers, retain goals across compaction.
-disable-model-invocation: true
+  track my goals, coordinate workers, retain goals across compaction,
+  before spawning a subagent, thread, or session, or starting work that
+  spans several turns.
 ---
 
 # Orchestrator
@@ -46,6 +47,7 @@ If a run is already active, retain its follow-up entry and answer without replac
 Create durable run state when work spans turns, has several goals, delegates, or waits on an external result.
 An explicit advisor-only request can restrict execution to workers for that run.
 For Claude Projects facts or reported coordinator mechanisms, read [platform evidence](reference/platform-evidence.md).
+Before spawning a subagent, thread, or session, read [oversee delegated work](reference/oversee-delegated-work.md).
 
 ## Process
 
@@ -135,6 +137,7 @@ Report the result, evidence, and any remaining limit.
 | `.claude/CLAUDE.md` | Claude instruction import. |
 | `reference/run-state.md` | Goal records, task authority, follow list, and active-root registry. |
 | `reference/recovery.md` | Cold-start and compaction recovery. |
+| `reference/oversee-delegated-work.md` | Spawner review of delegated work before it reaches the user. |
 | `reference/platform-evidence.md` | Official Projects sources and coordinator report boundaries. |
 | `reference/scheduling.md` | Optional existing gate commands and owned wake lifecycle. |
 | `reference/consult-the-orchestrator.md` | Executor consults and four-signal replies. |

package/.agents/skills/orchestrator/reference/oversee-delegated-work.md

@@ -0,0 +1,12 @@
+# Oversee delegated work
+
+Every agent that spawns a subagent, thread, or session owns that work until it reaches the user.
+Agents make mistakes. The spawner is a fresh second set of eyes that catches and corrects them before they reach the user.
+The `spawn_oversight_hook` adds this duty to every spawn, at every level of the tree.
+
+- Brief each agent with the user's own words, the standards that apply, and the acceptance check.
+- While it runs, read its progress. Wake a quiet agent with one concrete next step.
+- Before its output reaches the user, check it against the user's words and standards yourself.
+- Send the agent a correction when it misses, and check the corrected output the same way.
+- Give each piece of a multi-piece task its own reviewer or helper.
+- Show the user you are involved: say what you checked and what you corrected.

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -22,6 +22,11 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small
 
 ### Pull request submission rules
 
+**Prove the change where it runs before you open the pull request.** The body carries a
+"Proof in practice" section with each command you ran and its quoted output. A hook denies
+a new pull request without one. Read `~/.claude/docs/rule-guides/proof-before-pull-request.md`
+before you plan the proof run.
+
 **Open every pull request ready for review.** Pass `--draft` only when the owner asks
 for a draft.
 

package/bin/install.cursor-rules.test.mjs

@@ -124,9 +124,10 @@ test('seeds one editable policy and one native Codex routing hook', () => {
             group => group.matcher === 'multi_agent_v1__spawn_agent',
         );
         assert.equal(firstRoutingGroups.length, 1);
-        assert.equal(firstRoutingGroups[0].hooks.length, 2);
+        assert.equal(firstRoutingGroups[0].hooks.length, 3);
         assert.match(firstRoutingGroups[0].hooks[0].command, /subagent_model_routing\.mjs/);
         assert.match(firstRoutingGroups[0].hooks[1].command, /spawn_readiness_hook\.py/);
+        assert.match(firstRoutingGroups[0].hooks[2].command, /spawn_oversight_hook\.py/);
         const firstSpawnPromptGroups = firstCodexHooks.hooks.PreToolUse.filter(
             group => group.matcher === 'Agent|Task',
         );

package/bin/merge_profile_settings.mjs

@@ -65,6 +65,12 @@ export const DECLARED_PROFILE_SETTINGS = Object.freeze([
                 + '(mcp__claude-code-remote__set_session_title or mcp__ccd_session_mgmt__set_session_title) is allowed, '
                 + 'and so is a live test run of the account broker with '
                 + '`python ~/.claude/scripts/account_broker.py run`: the user installed both tools for these sessions',
+            'Moving instruction files out of the always-loaded rules folder of a Claude config directory '
+                + '(`~/.claude/rules` or a profile\'s `rules` folder) into a sibling on-demand folder in the same '
+                + 'config directory, and moving them back, is allowed when the task is to trim session-start context: '
+                + 'each file keeps its contents and stays on disk, and the move reverses with one more move. '
+                + 'This covers a plain move or rename with an index file that says when to open each moved file. '
+                + 'It does not cover deleting or editing a rule, or any change to settings, hooks or permissions.',
         ],
     },
 ]);

package/docs/rule-guides/proof-before-pull-request.md

@@ -0,0 +1,37 @@
+Back to the [rule entry](../../rules/proof-before-pull-request.md).
+
+# Proof before a pull request
+
+**When this applies:** Every session that builds a change and opens a pull request, in every project.
+
+## Rule
+
+Before you open a pull request, prove the change does its job where it will run.
+
+What counts as proof:
+- You ran the changed thing the way its user runs it, and you saw the effect it exists to produce. A hook fires in a live Claude Code session and changes what that session does. A script runs from its launcher on inputs like the ones it will meet. A skill or rule changes what a fresh agent does with an ordinary request.
+- You saw the failure first. Run the same scenario without your change and record what goes wrong. The proof is the difference between the two runs.
+- You covered the conditions the change will meet. That includes the case it should leave alone, and for session behavior a fresh session, a resumed session, a later turn, and a session after compaction.
+- The session under test got an ordinary request, worded as a task the way Jon would ask for it.
+
+Unit tests are welcome as extra evidence. The live run is the proof. A test you edited until it passed proves nothing.
+
+For a change to Claude Code behavior, such as a hook, skill, rule, setting, prompt or output style:
+- Spawn every session through the account broker, with the stream saved to a file:
+  python ~/.claude/scripts/account_broker.py run --product claude --report <broker-report.json> -- claude -p "<request>" --model claude-opus-5-5 --effort <level> --output-format stream-json --verbose > <stream.jsonl>
+- Run each later turn the same way with `--resume <session id>`. The broker resumes a session on the account that started it when that account has room.
+- Keep `--model` and `--effort` on every call. Without them the headless run uses claude-sonnet-5-5. Confirm the served model in the result's `modelUsage`.
+- Start the broker from your own shell, with your environment as is. The broker reads the account meters with your session's credentials and starts Claude without your session's variables.
+- Leave out `--bare` and `claude plugin eval`. Both drop the hooks and settings the user runs with.
+- Read the broker report for the account it chose. Read the stream for the hook events and their output, `permission_denials`, the final result, and the token usage on the result event.
+- When the broker exits 3 with action "wait", no account has room. Treat that as a blocked proof and report its reason and `resets_at`. Spawn Claude only through the broker.
+
+Report it in the pull request body under "Proof in practice". List each command you ran, quote the output lines that show the effect, state the difference between the runs with and without the change, and name anything still unproven.
+
+When you cannot prove it, leave the pull request unopened. Tell Jon in three short sentences what you could not run and which tool would make it possible. A blocked proof is an acceptable result, because it shows where tooling is missing.
+
+## Enforcement
+
+`hooks/blocking/pull_request_proof.py` reads the body of each new pull request before it opens. `pr_lifecycle_skill_gate.py` runs it on `gh pr create`, the `pull_request.py create` script, and each `mcp__*__create_pull_request` tool. The gate denies the call when the body has no "Proof in practice" heading, or when the text under that heading names no command in backticks. A `gh pr create` with no `--body` or `--body-file` is denied with a request for the body. Edits, merges, and pushes pass.
+
+The gate checks that the section is there and names a command. Whether the run proves the change stays a judgment for the author and the reviewer.

package/hooks/blocking/followup_pr_dedupe.py

@@ -79,7 +79,12 @@ def _option_value(all_arguments: list[str], all_option_names: frozenset[str]) ->
     return None
 
 
-def _body_from_arguments(all_arguments: list[str], working_directory: str) -> str | None:
+def body_from_arguments(all_arguments: list[str], working_directory: str) -> str | None:
+    """Return the body a gh-style argument list passes, or None when it passes none.
+
+    ``--body`` text comes back as given. A ``--body-file`` path is read from
+    the working directory. Standard input and an unreadable file give None.
+    """
     inline_body = _option_value(all_arguments, ALL_BODY_OPTIONS)
     if inline_body is not None:
         return inline_body
@@ -125,7 +130,7 @@ def _segment_draft(all_segment_tokens: list[str], working_directory: str) -> Pul
     program, all_arguments = segment_program_and_arguments(all_segment_tokens)
     if program != "gh" or all_arguments[: len(ALL_GH_CREATE_WORDS)] != ALL_GH_CREATE_WORDS:
         return None
-    body = _body_from_arguments(all_arguments, working_directory)
+    body = body_from_arguments(all_arguments, working_directory)
     repository = _repository_from_arguments(all_arguments, working_directory)
     if body is None or repository is None:
         return None

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -53,6 +53,7 @@ from hooks_constants.hook_specific_output_keys import (
 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 blocking.followup_pr_dedupe import duplicate_followup_reason
+from blocking.pull_request_proof import missing_proof_reason
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -198,7 +199,7 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for an unloaded skill or a second follow-up pull request for one parent.
+    """Return a deny for an unloaded skill, a new pull request with no proof, or a second follow-up.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
@@ -207,6 +208,9 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
         return None
     if _is_skill_unloaded(all_payload_fields):
         return _deny(DENY_REASON)
+    proof_reason = missing_proof_reason(all_payload_fields)
+    if proof_reason is not None:
+        return _deny(proof_reason)
     duplicate_reason = duplicate_followup_reason(all_payload_fields)
     return None if duplicate_reason is None else _deny(duplicate_reason)
 

package/hooks/blocking/pull_request_proof.py

@@ -0,0 +1,141 @@
+"""Deny a new pull request whose body carries no 'Proof in practice' section."""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections.abc import Mapping
+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 blocking.followup_pr_dedupe import body_from_arguments
+from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
+from hooks_constants.pull_request_proof_constants import (
+    ALL_GH_CREATE_WORDS,
+    ALL_PYTHON_PROGRAM_NAMES,
+    COMMAND_MARKER,
+    CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    LINE_SEPARATOR,
+    MISSING_BODY_REASON,
+    MISSING_PROOF_REASON,
+    NEXT_HEADING_PATTERN,
+    PROOF_HEADING_PATTERN,
+    PULL_REQUEST_SCRIPT_CREATE_WORD,
+    PULL_REQUEST_SCRIPT_NAME,
+)
+from hooks_constants.pytest_invocation import unquoted_token
+from hooks_constants.shell_command_pipeline import pipeline_segments_for_command
+from hooks_constants.shell_command_segments import token_basename
+from hooks_constants.shell_command_wrappers import (
+    all_wrapped_command_texts,
+    segment_program_and_arguments,
+)
+
+
+def _heading_level(line: str, heading_pattern: str) -> int | None:
+    heading = re.match(heading_pattern, line.strip(), re.IGNORECASE)
+    return None if heading is None else len(heading.group(1))
+
+
+def _lines_until_heading(all_lines: list[str], heading_level: int) -> list[str]:
+    for each_index, each_line in enumerate(all_lines):
+        next_level = _heading_level(each_line, NEXT_HEADING_PATTERN)
+        if next_level is not None and next_level <= heading_level:
+            return all_lines[:each_index]
+    return all_lines
+
+
+def proof_section(body: str) -> str | None:
+    """Return the text under the body's 'Proof in practice' heading, or None.
+
+    ::
+
+        "## Proof in practice\\nran `x`\\n## Notes" -> "ran `x`"
+        "## Summary\\nno proof heading"             -> None
+
+    The section runs to the next heading of the same or a higher level.
+    """
+    all_lines = body.splitlines()
+    for each_index, each_line in enumerate(all_lines):
+        heading_level = _heading_level(each_line, PROOF_HEADING_PATTERN)
+        if heading_level is not None:
+            all_section_lines = _lines_until_heading(all_lines[each_index + 1 :], heading_level)
+            return LINE_SEPARATOR.join(all_section_lines).strip()
+    return None
+
+
+def _script_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
+    if program == PULL_REQUEST_SCRIPT_NAME:
+        return all_arguments
+    if program not in ALL_PYTHON_PROGRAM_NAMES or not all_arguments:
+        return None
+    script_name = token_basename(unquoted_token(all_arguments[0]))
+    return all_arguments[1:] if script_name == PULL_REQUEST_SCRIPT_NAME else None
+
+
+def _script_create_arguments(program: str, all_arguments: list[str]) -> list[str] | None:
+    all_script_arguments = _script_arguments(program, all_arguments)
+    if all_script_arguments is None or all_script_arguments[:1] != [PULL_REQUEST_SCRIPT_CREATE_WORD]:
+        return None
+    return all_script_arguments[1:]
+
+
+def _create_arguments(all_segment_tokens: list[str]) -> list[str] | None:
+    program, all_arguments = segment_program_and_arguments(all_segment_tokens)
+    if program == "gh" and all_arguments[: len(ALL_GH_CREATE_WORDS)] == ALL_GH_CREATE_WORDS:
+        return all_arguments[len(ALL_GH_CREATE_WORDS) :]
+    return _script_create_arguments(program, all_arguments)
+
+
+def _shell_create_bodies(command: str, working_directory: str) -> list[str | None]:
+    return [
+        body_from_arguments(all_create_arguments, working_directory)
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+        if (all_create_arguments := _create_arguments(each_segment)) is not None
+    ]
+
+
+def _create_bodies(all_payload_fields: Mapping[str, object]) -> list[str | None]:
+    tool_name = all_payload_fields.get("tool_name")
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return []
+    if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
+        body = tool_input.get("body")
+        return [body if isinstance(body, str) else ""]
+    command = tool_input.get("command")
+    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+        return []
+    working_directory = all_payload_fields.get("cwd")
+    return _shell_create_bodies(
+        command, working_directory if isinstance(working_directory, str) else ""
+    )
+
+
+def missing_proof_reason(all_payload_fields: Mapping[str, object]) -> str | None:
+    """Return a deny reason when a new pull request's body has no proof, else None.
+
+    ::
+
+        gh pr create --body-file body.md, body has the section -> None
+        mcp__github__create_pull_request, body without it      -> MISSING_PROOF_REASON
+        gh pr create --fill                                     -> MISSING_BODY_REASON
+        gh pr edit, git push, any other tool                    -> None
+
+    The proof section is a 'Proof in practice' heading whose text names at
+    least one command in backticks.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+    """
+    for each_body in _create_bodies(all_payload_fields):
+        if each_body is None:
+            return MISSING_BODY_REASON
+        section = proof_section(each_body)
+        if not section or COMMAND_MARKER not in section:
+            return MISSING_PROOF_REASON
+    return None

package/hooks/blocking/test_followup_pr_dedupe.py

@@ -84,3 +84,11 @@ def test_powershell_body_file_is_denied(tmp_path: Path) -> None:
     }
     reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
     assert reason is not None and "pull request #1769" in reason
+
+
+def test_body_from_arguments_reads_inline_text_and_body_files(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text("From the file.", encoding="utf-8")
+    assert dedupe.body_from_arguments(["--body", "Inline."], "") == "Inline."
+    assert dedupe.body_from_arguments(["--body-file", "body.md"], str(tmp_path)) == "From the file."
+    assert dedupe.body_from_arguments(["--body-file", "-"], str(tmp_path)) is None
+    assert dedupe.body_from_arguments(["--fill"], str(tmp_path)) is None

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -13,6 +13,9 @@ if str(HOOKS_DIRECTORY) not in sys.path:
 from blocking import followup_pr_dedupe as gate_dedupe
 from blocking import pr_lifecycle_skill_gate as gate
 from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
+from hooks_constants.pull_request_proof_constants import MISSING_PROOF_REASON
+
+PROVEN_FOLLOWUP_BODY = "Follow-up to #1731\n\n## Proof in practice\nRan `python probe.py`.\n"
 
 
 def _transcript(tmp_path: Path, skill_name: str | None = None, compact: bool = False) -> Path:
@@ -61,7 +64,7 @@ def test_unloaded_pull_request_command_is_denied(tmp_path: Path) -> None:
 
 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, "")
+    assert _run_main(_payload("gh pr view", path)) == (0, "")
 
 
 def test_user_slash_command_loads_skill(tmp_path: Path) -> None:
@@ -127,7 +130,7 @@ def test_agent_id_with_path_separator_is_not_followed(tmp_path: Path) -> None:
 
 
 def test_unreadable_or_missing_transcript_allows_silently(tmp_path: Path) -> None:
-    payload = _payload("gh pr create", tmp_path / "missing.jsonl")
+    payload = _payload("gh pr view", tmp_path / "missing.jsonl")
     assert _run_main(payload) == (0, "")
     payload.pop("transcript_path")
     assert _run_main(payload) == (0, "")
@@ -237,7 +240,7 @@ def test_hook_has_its_own_pre_tool_use_registration() -> None:
 def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Path) -> None:
     payload = {
         "tool_name": "mcp__github__create_pull_request",
-        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
     }
     open_followup = {"number": 1769, "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1769", "body": "Follow-up to #1731"}
@@ -251,8 +254,14 @@ def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Pa
 def test_loaded_skill_allows_a_followup_when_the_read_fails(tmp_path: Path) -> None:
     payload = {
         "tool_name": "mcp__github__create_pull_request",
-        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": PROVEN_FOLLOWUP_BODY},
         "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
     }
     with patch.object(gate_dedupe, "read_open_pull_requests", side_effect=OSError("offline")):
         assert gate.decision_for(payload) is None
+
+
+def test_loaded_skill_still_denies_a_new_pull_request_without_proof(tmp_path: Path) -> None:
+    exit_code, output = _run_main(_payload("gh pr create --body 'Adds a gate.'", _transcript(tmp_path, "pr-lifecycle")))
+    assert exit_code == 0
+    assert json.loads(output)["hookSpecificOutput"]["permissionDecisionReason"] == MISSING_PROOF_REASON

package/hooks/blocking/test_pull_request_proof.py

@@ -0,0 +1,92 @@
+"""Behavior tests for the proof-in-practice check on a new pull request."""
+
+import sys
+from pathlib import Path
+
+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 pull_request_proof as gate
+from hooks_constants.pull_request_proof_constants import MISSING_BODY_REASON, MISSING_PROOF_REASON
+
+PROVEN_BODY = "## Summary\nAdds a gate.\n\n## Proof in practice\nRan `python run.py`.\n> denied\n"
+UNPROVEN_BODY = "## Summary\nAdds a gate.\n\n## Verification\nUnit tests pass.\n"
+
+
+def _shell(command: str, working_directory: Path | None = None) -> dict[str, object]:
+    return {
+        "tool_name": "Bash",
+        "tool_input": {"command": command},
+        "cwd": str(working_directory or ""),
+    }
+
+
+def _mcp_create(body: object) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "o", "repo": "r", "title": "t", "body": body},
+    }
+
+
+def test_proof_section_should_stop_at_a_heading_of_the_same_level() -> None:
+    body = "### Proof in practice\nran `a`\n#### Child\nkept\n### Local checks\ndropped"
+    assert gate.proof_section(body) == "ran `a`\n#### Child\nkept"
+
+
+def test_proof_section_should_return_none_without_the_heading() -> None:
+    assert gate.proof_section(UNPROVEN_BODY) is None
+
+
+def test_mcp_create_without_proof_should_be_denied() -> None:
+    assert gate.missing_proof_reason(_mcp_create(UNPROVEN_BODY)) == MISSING_PROOF_REASON
+
+
+def test_mcp_create_with_no_body_should_be_denied() -> None:
+    assert gate.missing_proof_reason(_mcp_create(None)) == MISSING_PROOF_REASON
+
+
+def test_mcp_create_with_proof_should_pass() -> None:
+    assert gate.missing_proof_reason(_mcp_create(PROVEN_BODY)) is None
+
+
+def test_heading_with_no_command_should_be_denied() -> None:
+    body = "## Proof in practice\nIt works.\n"
+    assert gate.missing_proof_reason(_mcp_create(body)) == MISSING_PROOF_REASON
+
+
+def test_gh_create_body_file_with_proof_should_pass(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(PROVEN_BODY, encoding="utf-8")
+    payload = _shell("gh pr create --draft --body-file body.md", tmp_path)
+    assert gate.missing_proof_reason(payload) is None
+
+
+def test_gh_create_body_file_without_proof_should_be_denied(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(UNPROVEN_BODY, encoding="utf-8")
+    payload = _shell("gh pr create -F body.md", tmp_path)
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_gh_create_with_fill_should_ask_for_a_body() -> None:
+    assert gate.missing_proof_reason(_shell("gh pr create --fill")) == MISSING_BODY_REASON
+
+
+def test_wrapped_gh_create_should_be_read() -> None:
+    payload = _shell("bash -c 'gh pr create --body \"no proof\"'")
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_pull_request_script_create_should_be_read(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text(UNPROVEN_BODY, encoding="utf-8")
+    payload = _shell("python3 scripts/pull_request.py create --body-file body.md", tmp_path)
+    assert gate.missing_proof_reason(payload) == MISSING_PROOF_REASON
+
+
+def test_other_pull_request_commands_should_pass() -> None:
+    for each_command in ("gh pr edit 3 --body x", "git push -u origin b", "gh pr view"):
+        assert gate.missing_proof_reason(_shell(each_command)) is None
+
+
+def test_other_tools_should_pass() -> None:
+    payload = {"tool_name": "mcp__github__update_pull_request", "tool_input": {"body": "x"}}
+    assert gate.missing_proof_reason(payload) is None

package/hooks/features/spawn-routing.md

@@ -1,10 +1,11 @@
 # Spawn routing
 
-This family reminds the agent to gather context before a spawn, adjusts thread requests when usage exceeds pace, and selects an allowed subagent model.
+This family reminds the agent to gather context before a spawn, tells it that it owns the spawned work, adjusts thread requests when usage exceeds pace, and selects an allowed subagent model.
 
 ## Checks
 
 - `routing/spawn_readiness_hook.py` adds context to a spawn that comes before a read step, or before an answered question or a settled-scope line. The spawn still runs.
+- `routing/spawn_oversight_hook.py` adds the orchestrator oversight directive to every spawn: watch the agent, check its output against the user's words and standards, and correct it before the output reaches the user. The spawn still runs.
 - `routing/thread_spawn_pace_hook.py` reshapes a thread request when usage is over pace or unreadable.
 - `routing/subagent_model_pin_hook.py` moves every Agent and Task subagent to Opus. A spawn that names Opus or Fable runs unchanged.
 - `routing/subagent_model_routing.mjs` allows a selected Luna model, remaps eligible requests, and denies unsupported model routing.
@@ -12,6 +13,7 @@ This family reminds the agent to gather context before a spawn, adjusts thread r
 ## When it fires
 
 - `routing/spawn_readiness_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, and `mcp__hearthbot__start_thread_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
+- `routing/spawn_oversight_hook.py` runs on `PreToolUse` with matchers `Agent|Task`, `multi_agent_v1__spawn_agent`, `Workflow|mcp__github__actions_run_trigger`, `mcp__hearthbot__start_thread_session`, and `mcp__hearthbot__start_rc_session`, each at `10` seconds in `hooks.json`. A workflow dispatch counts only when its inputs carry a `prompt`.
 - `routing/thread_spawn_pace_hook.py` runs on `PreToolUse`, matcher `mcp__hearthbot__start_thread_session`, timeout `30` seconds in `hooks.json`.
 - `routing/subagent_model_pin_hook.py` runs on `PreToolUse`, matcher `Agent|Task`, timeout `10` seconds in `hooks.json`.
 - `routing/subagent_model_routing.mjs` runs on `PreToolUse`, matcher `multi_agent_v1__spawn_agent`, timeout `10` seconds through the quoted Node command in `hooks.json`.
@@ -23,6 +25,7 @@ Preconditions:
 - Run each command from the repository root. Python and pytest cover the two Python scripts; Node covers the model router.
 
 - **Spawn readiness.** Input is a spawn after a read, a question, and its answer. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_readiness_hook.py -q`. The adjacent test observes no output for a ready spawn and reminder context for each missing step.
+- **Spawn oversight.** Input is a spawn from each registered tool, a subagent's own spawn, and a non-spawn call. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_spawn_oversight_hook.py -q`. The adjacent test observes the directive for every spawn and no output for the other calls.
 - **Thread pace.** Input is a thread spawn with usage over pace. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_thread_spawn_pace_hook.py -q`. The adjacent test observes updated tool input with the selected model, effort, and advisor line.
 - **Model pin.** Input is an Agent spawn that names a Sonnet model. Run `python -m pytest packages/claude-dev-env/hooks/routing/test_subagent_model_pin_hook.py -q`. The adjacent test observes updated tool input with model `opus`.
 - **Model routing.** Input is a `multi_agent_v1__spawn_agent` payload with a model choice. Run `node --test packages/claude-dev-env/hooks/routing/subagent_model_routing.test.mjs`. The adjacent test observes an allow or deny decision with the routed model.
@@ -30,5 +33,6 @@ Preconditions:
 ## Gotchas
 
 - `routing/spawn_readiness_hook.py` also runs after the pace hook on thread spawns. A reshaped request still gets the readiness check.
+- The oversight hook fires inside subagents too, so each level of the tree oversees the level below it. It emits `additionalContext` only and never blocks.
 - The readiness hook emits `additionalContext` only, so it never blocks. It passes subagent calls, read-only helper types, a non-object tool input, and unreadable transcripts.
 - The model router allows an advisor flag to bypass the Luna restriction. Its ordinary path denies unresolved or unsupported models.

package/hooks/hooks.json

@@ -19,6 +19,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/subagent_model_pin_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -34,6 +39,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -44,6 +54,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },
@@ -159,6 +174,21 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_readiness_hook.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__hearthbot__start_rc_session",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/routing/spawn_oversight_hook.py",
+            "timeout": 10
           }
         ]
       },

package/hooks/hooks_constants/pre_tool_use_context_runner.py

@@ -0,0 +1,38 @@
+"""Shared main loop for PreToolUse hooks that only add context.
+
+Reads the payload from stdin, asks the hook's decide function for an output,
+and writes it as JSON. Exit status is always 0, so the tool call runs; a
+decide function that raises leaves the call with no output.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Callable
+
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+
+
+def run_context_hook(
+    decide_hook_output: Callable[[dict[str, object]], dict[str, object] | None],
+) -> int:
+    """Print the decided output for the stdin payload, or nothing.
+
+    Args:
+        decide_hook_output: Maps the parsed payload to an output or None.
+
+    Returns:
+        0 in every case; the context travels in the JSON output.
+    """
+    hook_payload = read_hook_input_dictionary_from_stdin()
+    if hook_payload is None:
+        return 0
+    try:
+        hook_output = decide_hook_output(hook_payload)
+    except Exception:
+        return 0
+    if hook_output is not None:
+        sys.stdout.write(json.dumps(hook_output))
+        sys.stdout.flush()
+    return 0

package/hooks/hooks_constants/pull_request_proof_constants.py

@@ -0,0 +1,27 @@
+"""Constants for the proof-in-practice check on a new pull request."""
+
+PROOF_HEADING_PATTERN = r"^(#{1,6})[ \t]+proof in practice[ \t]*#*[ \t]*$"
+NEXT_HEADING_PATTERN = r"^(#{1,6})[ \t]+\S"
+COMMAND_MARKER = "`"
+LINE_SEPARATOR = "\n"
+ALL_GH_CREATE_WORDS = ["pr", "create"]
+PULL_REQUEST_SCRIPT_NAME = "pull_request.py"
+PULL_REQUEST_SCRIPT_CREATE_WORD = "create"
+ALL_PYTHON_PROGRAM_NAMES = frozenset({"python", "python3", "py"})
+CREATE_PULL_REQUEST_TOOL_SUFFIX = "__create_pull_request"
+PROOF_GUIDE_PATH = "~/.claude/docs/rule-guides/proof-before-pull-request.md"
+MISSING_BODY_REASON = (
+    "Pass the pull request body with --body or --body-file so this gate can read its"
+    " 'Proof in practice' section. Read " + PROOF_GUIDE_PATH + " for what counts as proof."
+)
+MISSING_PROOF_REASON = (
+    "This pull request body has no 'Proof in practice' section with the commands you ran."
+    " Before you open a pull request, run the changed thing the way its user runs it,"
+    " run the same scenario without the change, and quote the output lines that show"
+    " the difference. For a hook, skill, rule, setting, prompt or output style, spawn"
+    " each test session through the account broker. Then add a 'Proof in practice'"
+    " heading to the body that lists each command in backticks, quotes the output, states"
+    " the difference between the runs, and names anything still unproven. When you cannot"
+    " prove the change, leave the pull request unopened and tell the user what you could"
+    " not run. Read " + PROOF_GUIDE_PATH + " for the full rule."
+)

package/hooks/hooks_constants/spawn_oversight_hook_constants.py

@@ -0,0 +1,40 @@
+"""Constants for the spawn oversight PreToolUse hook.
+
+Groups: the spawn tools it answers, the workflow dispatch that carries an
+agent prompt, the payload keys it reads, and the
+oversight directive it adds to every spawn.
+"""
+
+from __future__ import annotations
+
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+PRE_TOOL_USE_EVENT_NAME = "PreToolUse"
+ADDITIONAL_CONTEXT_KEY = "additionalContext"
+
+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"
+
+ALL_SPAWN_TOOL_NAMES = frozenset(
+    {
+        "Agent",
+        "Task",
+        "Workflow",
+        "multi_agent_v1__spawn_agent",
+        "mcp__hearthbot__start_thread_session",
+        "mcp__hearthbot__start_rc_session",
+    }
+)
+
+SPAWN_OVERSIGHT_DIRECTIVE = (
+    "You own the work this spawn starts. Load the orchestrator skill and follow "
+    "its oversee delegated work reference. While the agent runs, read its progress "
+    "and wake it with one next step when it goes quiet. Before its output "
+    "reaches the user, check it against the user's own words and standards, and "
+    "send the agent a correction when it misses. Give each piece of a "
+    "multi-piece task its own reviewer or helper. Tell the user you are "
+    "checking the work."
+)

package/hooks/hooks_constants/test_pre_tool_use_context_runner.py

@@ -0,0 +1,47 @@
+import io
+import json
+import sys
+
+import pytest
+
+from hooks_constants.pre_tool_use_context_runner import run_context_hook
+
+
+def _feed_stdin(monkeypatch: pytest.MonkeyPatch, text: str) -> None:
+    monkeypatch.setattr(sys, "stdin", io.TextIOWrapper(io.BytesIO(text.encode("utf-8"))))
+
+
+def test_prints_the_decided_output(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Agent"}))
+    exit_code = run_context_hook(lambda payload: {"seen": payload["tool_name"]})
+    assert exit_code == 0
+    assert json.loads(capsys.readouterr().out) == {"seen": "Agent"}
+
+
+def test_prints_nothing_when_the_decision_is_none(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Bash"}))
+    assert run_context_hook(lambda payload: None) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_prints_nothing_for_empty_stdin(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    _feed_stdin(monkeypatch, "")
+    assert run_context_hook(lambda payload: {"never": True}) == 0
+    assert capsys.readouterr().out == ""
+
+
+def test_prints_nothing_and_exits_zero_when_the_decision_raises(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    def _raise(payload: dict[str, object]) -> dict[str, object] | None:
+        raise KeyError(payload["missing"])
+
+    _feed_stdin(monkeypatch, json.dumps({"tool_name": "Agent"}))
+    assert run_context_hook(_raise) == 0
+    assert capsys.readouterr().out == ""

package/hooks/routing/spawn_oversight_hook.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: tell the spawning session it owns the work it delegates.
+
+Registered on every tool that starts another agent: ``Agent``, ``Task``,
+``Workflow``, ``multi_agent_v1__spawn_agent``,
+``mcp__hearthbot__start_thread_session``, and
+``mcp__hearthbot__start_rc_session``, plus a workflow dispatch whose inputs
+carry a ``prompt`` for an agent. Each spawn gets the oversight directive
+as ``additionalContext``, so the spawn runs and keeps its normal permission
+flow. A subagent that spawns its own agents gets the same directive, so every
+level of the tree oversees the level below it.
+
+::
+
+    Agent {"prompt": "Do X."}        -> additionalContext: the directive
+    actions trigger {"method": "run_workflow",
+                     "inputs": {"prompt": "Do X."}}
+                                     -> additionalContext: the directive
+    actions trigger {"method": "cancel_workflow_run"}
+                                     -> no output
+    Bash {"command": "ls"}           -> no output
+    Agent "not an object"            -> no output
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+)
+from hooks_constants.pre_tool_use_context_runner import run_context_hook
+from hooks_constants.spawn_oversight_hook_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    ALL_SPAWN_TOOL_NAMES,
+    DISPATCH_INPUTS_KEY,
+    DISPATCH_METHOD_INPUT_KEY,
+    DISPATCH_PROMPT_INPUT_KEY,
+    DISPATCH_RUN_WORKFLOW_METHOD,
+    PRE_TOOL_USE_EVENT_NAME,
+    SPAWN_OVERSIGHT_DIRECTIVE,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    WORKFLOW_DISPATCH_TOOL_NAME,
+)
+
+
+def starts_an_agent(tool_name: object, all_tool_input_fields: dict[str, object]) -> bool:
+    """Return True when the call starts an agent: a spawn tool or a prompt dispatch.
+
+    Args:
+        tool_name: The tool the session called.
+        all_tool_input_fields: The tool input.
+    """
+    if tool_name in ALL_SPAWN_TOOL_NAMES:
+        return True
+    if tool_name != WORKFLOW_DISPATCH_TOOL_NAME:
+        return False
+    if all_tool_input_fields.get(DISPATCH_METHOD_INPUT_KEY) != DISPATCH_RUN_WORKFLOW_METHOD:
+        return False
+    workflow_inputs = all_tool_input_fields.get(DISPATCH_INPUTS_KEY)
+    return isinstance(workflow_inputs, dict) and isinstance(
+        workflow_inputs.get(DISPATCH_PROMPT_INPUT_KEY), str
+    )
+
+
+def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object] | None:
+    """Return the oversight directive for a spawn call, else None.
+
+    Args:
+        all_hook_fields: The parsed PreToolUse payload.
+    """
+    all_tool_input_fields = all_hook_fields.get(TOOL_INPUT_KEY)
+    if not isinstance(all_tool_input_fields, dict):
+        return None
+    if not starts_an_agent(all_hook_fields.get(TOOL_NAME_KEY), all_tool_input_fields):
+        return None
+    return {
+        HOOK_SPECIFIC_OUTPUT_KEY: {
+            HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY: SPAWN_OVERSIGHT_DIRECTIVE,
+        }
+    }
+
+
+def main() -> int:
+    """Run the hook on the stdin payload; always 0."""
+    return run_context_hook(decide_hook_output)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/routing/spawn_readiness_hook.py

@@ -35,7 +35,7 @@ routing_directory = str(Path(__file__).resolve().parent)
 if routing_directory not in sys.path:
     sys.path.insert(0, routing_directory)
 
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.pre_tool_use_context_runner import run_context_hook
 from hooks_constants.spawn_readiness_hook_constants import (
     ADDITIONAL_CONTEXT_KEY,
     AGENT_ID_KEY,
@@ -250,19 +250,8 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
 
 
 def main() -> int:
-    """Read the PreToolUse payload and print the reminder when the spawn is not ready.
-
-    Returns:
-        0 in every case; the reminder travels in the JSON output.
-    """
-    hook_payload = read_hook_input_dictionary_from_stdin()
-    if hook_payload is None:
-        return 0
-    hook_output = decide_hook_output(hook_payload)
-    if hook_output is not None:
-        sys.stdout.write(json.dumps(hook_output))
-        sys.stdout.flush()
-    return 0
+    """Run the hook on the stdin payload; always 0."""
+    return run_context_hook(decide_hook_output)
 
 
 if __name__ == "__main__":

package/hooks/routing/test_spawn_oversight_hook.py

@@ -0,0 +1,104 @@
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import spawn_oversight_hook
+from hooks_constants.spawn_oversight_hook_constants import SPAWN_OVERSIGHT_DIRECTIVE
+
+HOOK_SCRIPT = Path(__file__).resolve().parent / "spawn_oversight_hook.py"
+
+
+def _expected_output() -> dict[str, object]:
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "additionalContext": SPAWN_OVERSIGHT_DIRECTIVE,
+        }
+    }
+
+
+@pytest.mark.parametrize(
+    "tool_name",
+    [
+        "Agent",
+        "Task",
+        "Workflow",
+        "multi_agent_v1__spawn_agent",
+        "mcp__hearthbot__start_thread_session",
+        "mcp__hearthbot__start_rc_session",
+    ],
+)
+def test_every_spawn_tool_gets_the_oversight_directive(tool_name: str) -> None:
+    payload = {"tool_name": tool_name, "tool_input": {"prompt": "Do X."}}
+    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+
+
+def test_a_subagent_spawning_its_own_agent_gets_the_directive() -> None:
+    payload = {
+        "tool_name": "Agent",
+        "tool_input": {"prompt": "Do X."},
+        "agent_id": "agent_child",
+    }
+    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+
+
+def test_a_read_only_helper_spawn_gets_the_directive() -> None:
+    payload = {
+        "tool_name": "Agent",
+        "tool_input": {"subagent_type": "Explore", "prompt": "Find X."},
+    }
+    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+
+
+def test_a_workflow_dispatch_with_an_agent_prompt_gets_the_directive() -> None:
+    payload = {
+        "tool_name": "mcp__github__actions_run_trigger",
+        "tool_input": {"method": "run_workflow", "inputs": {"prompt": "Do X."}},
+    }
+    assert spawn_oversight_hook.decide_hook_output(payload) == _expected_output()
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        {
+            "tool_name": "mcp__github__actions_run_trigger",
+            "tool_input": {"method": "cancel_workflow_run", "run_id": 1},
+        },
+        {
+            "tool_name": "mcp__github__actions_run_trigger",
+            "tool_input": {"method": "run_workflow", "inputs": {"head": "branch"}},
+        },
+        {"tool_name": "Bash", "tool_input": {"command": "ls"}},
+        {"tool_name": "mcp__hearthbot__reply", "tool_input": {"text": "hi"}},
+        {"tool_name": "Agent", "tool_input": "not an object"},
+        {"tool_input": {"prompt": "Do X."}},
+    ],
+)
+def test_other_calls_get_no_output(payload: dict[str, object]) -> None:
+    assert spawn_oversight_hook.decide_hook_output(payload) is None
+
+
+def test_script_prints_the_directive_for_a_spawn() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input=json.dumps({"tool_name": "Agent", "tool_input": {"prompt": "Do X."}}),
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert json.loads(completed.stdout) == _expected_output()
+
+
+def test_script_prints_nothing_for_empty_stdin() -> None:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input="",
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert completed.stdout == ""

package/hooks/routing/test_spawn_readiness_hook.py

@@ -368,3 +368,15 @@ def test_should_quiet_a_codex_spawn_whose_brief_settles_scope(tmp_path: Path) ->
     assert stdout == ""
     [log_record] = _decision_log(tmp_path)
     assert log_record["outcome"] == "scope_settled"
+
+
+def test_should_print_nothing_for_empty_stdin(tmp_path: Path) -> None:
+    completed = subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT)],
+        input="",
+        capture_output=True,
+        text=True,
+        env={**os.environ, "HOME": str(tmp_path)},
+        check=True,
+    )
+    assert completed.stdout == ""

package/package.json

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

package/rules/proof-before-pull-request.md

@@ -0,0 +1,7 @@
+# Proof before a pull request
+
+**When:** Before you open a pull request.
+
+Run the change where it runs, with and without it, and quote both results under "Proof in practice" in the body. A hook denies a body without one. Unproven: leave it unopened and tell the user.
+
+**Full text:** [`docs/rule-guides/proof-before-pull-request.md`](../docs/rule-guides/proof-before-pull-request.md).

package/rules/question-presentation.md

@@ -1,12 +1,9 @@
 # Present questions clearly
 
-Before asking for input, give a short formatted brief in chat. Put the context and the effect of each choice there. Add a visual or artifact only when it helps the decision.
+Before asking, give a short formatted chat brief with context and each choice's effect. Add helpful visuals or artifacts.
 
-For Codex, when a visual comparison helps, discover callable tools for Page creation, visualization upload, and Page opening. Create the comparison, upload its visualization, and open its Page in the current task before asking. If a tool is unavailable, creation, upload, or opening fails, or opening queues, put the comparison in chat before asking. Inline Visualize references appear only in final replies. Use the user's submitted answer for the decision. An async dispatch acknowledgement or saved visual supplies context only. Wait for the answer before work that depends on it.
+For Codex visual comparisons, find Page creation, visualization upload, and Page opening tools. Create the comparison, upload its visualization, and open its Page here before asking. If tools are missing, steps fail, or opening queues, compare in chat before asking. Put inline Visualize references only in final replies. An async acknowledgement or saved visual is context only; wait for and use the submitted answer before dependent work.
 
-Ask one short, self-contained question with two or three clear choices. Use short labels, and keep each supported choice description to one short sentence. Use the same labels in the chat brief, comparison, and picker.
+Ask one short, self-contained question with two or three choices. Give each a short label and one short sentence. Reuse labels in the brief, comparison, and picker.
 
-Discover the current session's native question tool and its schema. Claude may expose `AskUserQuestion`.
-Codex may expose `request_user_input_async` or `request_user_input`. Follow the tool's mode restrictions.
-Put the question in its declared title or question field and choices in its declared string or object fields.
-When no native tool is usable, ask the short question and choices in chat.
+Find the native question tool and schema. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question in its title or question field and choices in string or object fields. If unusable, ask in chat.

package/scripts/tests/test_rule_load_scopes.py

@@ -18,6 +18,7 @@ ALWAYS_ON_RULE_NAMES = frozenset(
         "filesystem-search.md",
         "memory-stores-durable-facts.md",
         "no-contrast-framing.md",
+        "proof-before-pull-request.md",
         "question-presentation.md",
         "research-mode.md",
         "request-scope.md",