claude-dev-env 8.98.4 → 8.98.7

package/hooks/blocking/test_open_tasks_stop_gate.py

@@ -79,7 +79,7 @@ def test_should_allow_when_every_open_task_is_reported_as_blocked_or_open(
             {"id": "3", "subject": "Write tests", "status": "completed"},
         ],
     )
-    reply_text = "Tests written.\nBlocked: Rotate the deploy key - the owner approves the secret\n- Open: #2 - checks running"
+    reply_text = "Tests written.\nBlocked: Rotate the deploy key - the owner pastes the secret\n- Open: #2 - checks running"
     assert run_gate(monkeypatch, capsys, reply_text) == (0, "")
 
 
@@ -238,7 +238,7 @@ def test_should_allow_cursor_when_the_last_assistant_text_reports_the_item(
         [
             cursor_todo_record(all_todos, False, "Working."),
             {"role": "assistant", "message": {"content": [
-                {"type": "text", "text": "Blocked: rotate the deploy key - the owner must approve the org secret"}
+                {"type": "text", "text": "Blocked: rotate the deploy key - the owner pastes the org secret"}
             ]}},
         ],
     )
@@ -510,3 +510,136 @@ def test_should_mark_the_right_item_for_a_done_index_after_a_continuation(
     assert "Submit both APKs" in reason_text
     assert "Read the schema" not in reason_text
     assert "Set rows in Neon" not in reason_text
+
+
+DECISION_BLOCKED_REPLY = "Branch pushed.\nBlocked: #ask-1 - your OK to merge the app branch first."
+
+
+def user_prompt_record(prompt_text: str) -> dict[str, object]:
+    return {"type": "user", "message": {"role": "user", "content": prompt_text}}
+
+
+def tool_call_record(tool_name: str) -> dict[str, object]:
+    tool_use = {"type": "tool_use", "id": "q1", "name": tool_name, "input": {}}
+    return {"type": "assistant", "message": {"role": "assistant", "content": [tool_use]}}
+
+
+def test_should_block_a_decision_blocked_line_with_no_card_this_turn(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    transcript_path = write_records(tmp_path / "s.jsonl", [user_prompt_record("Merge the release branch")])
+    reason_text = block_reason(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path)
+    assert "AskUserQuestion" in reason_text
+    assert "your OK to merge" in reason_text
+
+
+@pytest.mark.parametrize(
+    "card_tool_name",
+    ["AskUserQuestion", "mcp__hearthbot__ask_decision", "mcp__hearthbot__request_decision"],
+)
+def test_should_allow_a_decision_blocked_line_after_a_card_this_turn(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path, card_tool_name: str
+) -> None:
+    record_ask("Merge the release branch")
+    transcript_path = write_records(
+        tmp_path / "s.jsonl", [user_prompt_record("Merge the release branch"), tool_call_record(card_tool_name)]
+    )
+    assert run_gate(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path) == (0, "")
+
+
+def test_should_block_a_decision_blocked_line_when_the_card_came_in_an_earlier_turn(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    transcript_path = write_records(
+        tmp_path / "s.jsonl",
+        [
+            tool_call_record("AskUserQuestion"),
+            user_prompt_record("Merge the release branch"),
+        ],
+    )
+    assert "AskUserQuestion" in block_reason(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path)
+
+
+def test_should_allow_a_blocked_line_for_an_input_the_user_supplies(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Rotate the deploy key")
+    transcript_path = write_records(tmp_path / "s.jsonl", [user_prompt_record("Rotate the deploy key")])
+    reply_text = "Key script ready.\nBlocked: #ask-1 - the new deploy key secret, pasted into the session"
+    assert run_gate(monkeypatch, capsys, reply_text, transcript_path) == (0, "")
+
+
+def test_should_keep_the_card_through_stop_hook_feedback(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    transcript_path = write_records(
+        tmp_path / "s.jsonl",
+        [
+            user_prompt_record("Merge the release branch"),
+            tool_call_record("AskUserQuestion"),
+            {"type": "user", "isMeta": True, "message": {"content": "Stop hook feedback"}},
+        ],
+    )
+    assert run_gate(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path) == (0, "")
+
+
+def test_should_ignore_a_card_call_copied_into_an_api_request_blob(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    blob_record = {**tool_call_record("AskUserQuestion"), "type": "api-request-blob"}
+    transcript_path = write_records(tmp_path / "s.jsonl", [user_prompt_record("Merge the release branch"), blob_record])
+    assert "AskUserQuestion" in block_reason(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path)
+
+
+def test_should_allow_an_input_blocked_line_that_says_whether(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    transcript_path = write_records(tmp_path / "s.jsonl", [user_prompt_record("Merge the release branch")])
+    input_reply = "Branch pushed.\nBlocked: #ask-1 - paste the log showing whether the migration ran."
+    assert run_gate(monkeypatch, capsys, input_reply, transcript_path) == (0, "")
+
+
+def test_should_start_a_new_turn_at_an_image_only_prompt(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    image_prompt = {"type": "user", "message": {"role": "user", "content": [{"type": "image", "source": {}}]}}
+    transcript_path = write_records(
+        tmp_path / "s.jsonl",
+        [user_prompt_record("Merge the release branch"), tool_call_record("AskUserQuestion"), image_prompt],
+    )
+    assert "AskUserQuestion" in block_reason(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path)
+
+
+def test_should_allow_a_decision_blocked_line_after_a_codex_request_user_input_call(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Merge the release branch")
+    user_message = {"type": "response_item", "payload": {"type": "message", "role": "user", "content": []}}
+    card_call = {"type": "response_item", "payload": {"type": "function_call", "name": "request_user_input", "arguments": "{}"}}
+    transcript_path = write_records(tmp_path / "rollout.jsonl", [user_message, card_call])
+    assert run_gate(monkeypatch, capsys, DECISION_BLOCKED_REPLY, transcript_path) == (0, "")
+
+
+def test_should_allow_a_blocked_line_for_a_device_step_the_user_takes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    record_ask("Install the runner")
+    transcript_path = write_records(tmp_path / "s.jsonl", [user_prompt_record("Install the runner")])
+    reply_text = "Installer built.\nBlocked: #ask-1 - run the installer on your PC and paste the log"
+    assert run_gate(monkeypatch, capsys, reply_text, transcript_path) == (0, "")
+
+
+def test_should_leave_a_cursor_decision_blocked_line_alone(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_cursor_transcript(
+        tmp_path / "cursor.jsonl",
+        [{"role": "assistant", "message": {"content": [{"type": "text", "text": DECISION_BLOCKED_REPLY}]}}],
+    )
+    assert run_cursor_gate(monkeypatch, capsys, transcript_path) == {}

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -103,6 +103,11 @@ def test_executable_word_lists_skips_a_comment_and_resumes_on_the_next_line() ->
 def test_executable_word_lists_joins_a_line_continuation() -> None:
     assert gate.executable_word_lists("git \\\npush origin") == [["git", "push", "origin"]]
     assert gate.executable_word_lists("git\\\n#note; git push") == [["git#note"], ["git", "push"]]
+    assert gate.executable_word_lists("echo a\\\\\n#; git push") == [["echo", "a\\"]]
+    assert gate.executable_word_lists('"gi\\\nt" push origin') == [["git", "push", "origin"]]
+    assert gate.executable_word_lists('echo "a\\\\\nb"') == [["echo", "a\\\nb"]]
+    assert gate.executable_word_lists('g"i\\\nt" push origin') == [["git", "push", "origin"]]
+    assert gate.executable_word_lists("echo 'a\\\nb'") == [["echo", "a\\\nb"]]
 
 
 def test_executable_word_lists_keeps_the_other_segments_beside_a_trailing_backslash() -> None:

package/hooks/blocking/test_reply_length_gate.py

@@ -1065,3 +1065,14 @@ def test_should_read_gh_comment_body_and_skip_pr_create() -> None:
     assert reply_length_gate.github_comment_texts("Bash", {"command": flagged_command}) == [f"note=x. {LONG_GITHUB_COMMENT}"]
     chained_command = f"git push && {comment_command}"
     assert reply_length_gate.github_comment_texts("Bash", {"command": chained_command}) == [LONG_GITHUB_COMMENT]
+
+
+def test_should_report_an_over_long_comment_text_with_the_comment_instruction() -> None:
+    violation = reply_length_gate.comment_length_violation(LONG_GITHUB_COMMENT)
+    assert violation is not None
+    assert violation.endswith(reply_length_gate.COMMENT_RETRY_INSTRUCTION)
+
+
+def test_should_pass_a_comment_text_whose_long_part_sits_in_a_details_block() -> None:
+    comment_text = "Fixed.\n<details><summary>Log</summary>\n" + LONG_GITHUB_COMMENT + "\n</details>"
+    assert reply_length_gate.comment_length_violation(comment_text) is None

package/hooks/blocking/test_resolve_thread_reply_gate.py

@@ -0,0 +1,199 @@
+"""Behavior tests for the gate that holds a review thread resolve until a reply posts."""
+
+import json
+import subprocess
+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 resolve_thread_reply_gate as gate
+from hooks_constants.resolve_thread_reply_gate_constants import MISSING_REPLY_REASON
+from transcript_skill_scan import TranscriptToolCall
+
+GATE_PATH = Path(__file__).resolve().parent / "resolve_thread_reply_gate.py"
+RESOLVE_TOOL_NAME = "mcp__github__resolve_review_thread"
+REPLY_TOOL_NAME = "mcp__github__add_reply_to_pull_request_comment"
+HOOK_DENIAL_TEXT = "PreToolUse:mcp__github__add_reply_to_pull_request_comment hook error: too many sentences"
+
+
+def _prompt(text: str) -> str:
+    return json.dumps({"type": "user", "message": {"content": text}})
+
+
+def _call(tool_use_id: str, tool_name: str, tool_input: dict[str, object] | None = None) -> str:
+    tool_use = {"type": "tool_use", "id": tool_use_id, "name": tool_name, "input": tool_input or {}}
+    return json.dumps({"type": "assistant", "message": {"content": [tool_use]}})
+
+
+def _result(tool_use_id: str, is_error: bool = False, text: str = "ok") -> str:
+    tool_result = {"type": "tool_result", "tool_use_id": tool_use_id, "is_error": is_error, "content": text}
+    return json.dumps({"type": "user", "message": {"content": [tool_result]}})
+
+
+def _write_transcript(tmp_path: Path, all_lines: list[str]) -> Path:
+    transcript_path = tmp_path / "session.jsonl"
+    transcript_path.write_text("\n".join(all_lines) + "\n", encoding="utf-8")
+    return transcript_path
+
+
+def _resolve_payload(transcript_path: Path) -> dict[str, object]:
+    return {
+        "hook_event_name": "PreToolUse",
+        "tool_name": RESOLVE_TOOL_NAME,
+        "tool_input": {"threadId": "PRRT_1"},
+        "transcript_path": str(transcript_path),
+    }
+
+
+def _deny_reason(decision: dict[str, object] | None) -> str | None:
+    if decision is None:
+        return None
+    hook_output = decision["hookSpecificOutput"]
+    assert isinstance(hook_output, dict)
+    assert hook_output["permissionDecision"] == "deny"
+    return str(hook_output["permissionDecisionReason"])
+
+
+def should_allow_a_resolve_after_a_reply_that_posted(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Address the review threads."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "Fixed in `abc1234`."}),
+            _result("reply-1"),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert gate.decision_for(_resolve_payload(transcript_path)) is None
+
+
+def should_deny_a_resolve_after_a_reply_a_hook_refused(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Address the review threads."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "A long reply."}),
+            _result("reply-1", is_error=True, text=HOOK_DENIAL_TEXT),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert _deny_reason(gate.decision_for(_resolve_payload(transcript_path))) == MISSING_REPLY_REASON
+
+
+def should_deny_a_resolve_with_no_reply(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [_prompt("Address the review threads."), _call("resolve-1", RESOLVE_TOOL_NAME)],
+    )
+    assert _deny_reason(gate.decision_for(_resolve_payload(transcript_path))) == MISSING_REPLY_REASON
+
+
+def should_deny_a_second_resolve_after_one_reply(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Address the review threads."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "Fixed in `abc1234`."}),
+            _result("reply-1"),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+            _result("resolve-1"),
+            _call("resolve-2", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert _deny_reason(gate.decision_for(_resolve_payload(transcript_path))) == MISSING_REPLY_REASON
+
+
+def should_allow_a_second_resolve_after_two_replies(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Address the review threads."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "Fixed in `abc1234`."}),
+            _result("reply-1"),
+            _call("reply-2", REPLY_TOOL_NAME, {"body": "Fixed in `def5678`."}),
+            _result("reply-2"),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+            _result("resolve-1"),
+            _call("resolve-2", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert gate.decision_for(_resolve_payload(transcript_path)) is None
+
+
+def should_deny_a_resolve_whose_reply_came_before_the_last_prompt(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Reply on the thread."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "Fixed in `abc1234`."}),
+            _result("reply-1"),
+            _prompt("Now resolve the other thread."),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert _deny_reason(gate.decision_for(_resolve_payload(transcript_path))) == MISSING_REPLY_REASON
+
+
+def should_allow_a_retry_after_a_resolve_error(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [
+            _prompt("Address the review threads."),
+            _call("reply-1", REPLY_TOOL_NAME, {"body": "Fixed in `abc1234`."}),
+            _result("reply-1"),
+            _call("resolve-1", RESOLVE_TOOL_NAME),
+            _result("resolve-1", is_error=True, text="Bad gateway"),
+            _call("resolve-2", RESOLVE_TOOL_NAME),
+        ],
+    )
+    assert gate.decision_for(_resolve_payload(transcript_path)) is None
+
+
+def should_allow_a_resolve_when_the_transcript_cannot_be_read(tmp_path: Path) -> None:
+    assert gate.decision_for(_resolve_payload(tmp_path / "missing.jsonl")) is None
+
+
+def should_ignore_tools_other_than_a_resolve(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(tmp_path, [_prompt("Reply on the thread.")])
+    payload = _resolve_payload(transcript_path) | {"tool_name": REPLY_TOOL_NAME}
+    assert gate.decision_for(payload) is None
+
+
+def should_read_a_resolve_tool_from_any_mcp_server() -> None:
+    assert gate.is_resolve_call("mcp__github_enterprise__resolve_review_thread")
+    assert not gate.is_resolve_call("mcp__github__resolve_review_threads")
+    assert not gate.is_resolve_call(None)
+
+
+def should_count_a_gh_api_reply_command_as_a_reply() -> None:
+    reply_command = "gh api repos/o/r/pulls/7/comments/99/replies -f body=Fixed."
+    assert gate.is_reply_call(TranscriptToolCall("Bash", {"command": reply_command}, True))
+    graphql_command = "gh api graphql -f query='mutation { addPullRequestReviewThreadReply(input: {}) { comment { id } } }'"
+    assert gate.is_reply_call(TranscriptToolCall("Bash", {"command": graphql_command}, True))
+    assert gate.is_reply_call(TranscriptToolCall(REPLY_TOOL_NAME, {}, True))
+    assert not gate.is_reply_call(TranscriptToolCall("mcp__github__add_issue_comment", {}, True))
+
+
+def should_report_a_posted_reply_from_transcript_lines() -> None:
+    all_lines = [_prompt("Go."), _call("reply-1", REPLY_TOOL_NAME), _result("reply-1")]
+    assert gate.has_posted_reply_since_last_resolve(all_lines)
+    assert not gate.has_posted_reply_since_last_resolve(all_lines[:2])
+
+
+def should_print_the_deny_when_run_as_a_hook(tmp_path: Path) -> None:
+    transcript_path = _write_transcript(
+        tmp_path,
+        [_prompt("Address the review threads."), _call("resolve-1", RESOLVE_TOOL_NAME)],
+    )
+    completed_process = subprocess.run(
+        [sys.executable, str(GATE_PATH)],
+        input=json.dumps(_resolve_payload(transcript_path)),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    assert completed_process.returncode == 0
+    assert _deny_reason(json.loads(completed_process.stdout)) == MISSING_REPLY_REASON

package/hooks/features/conduct-gates.md

@@ -17,6 +17,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
+- `blocking/resolve_thread_reply_gate.py` denies a review thread resolve until the agent's own transcript shows a reply on a thread that posted after the last user prompt and that no successful resolve has spent. Each successful resolve spends one posted reply. A reply is an `add_reply_to_pull_request_comment` call, or a `gh api` call to a comment's `replies` endpoint or to `addPullRequestReviewThreadReply`. A reply whose result is an error, such as a refusal from `blocking/reply_length_gate.py`, does not count. With no readable transcript, the resolve passes.
 - `blocking/verify_before_commit_gate.py` denies a `git commit` in a repository with a `.claude/skills/verify` or `.agents/skills/verify` directory until the `verify` skill loads after the last user prompt, through a Skill call or the `/verify` command in that prompt. It reads the committed paths from the staged diff, the tracked changes for `-a`, and the paths of each `git add` earlier in the same command, and passes a commit whose paths are all docs, images, or test files.
 - `blocking/build_eval_before_eval_write_gate.py` denies a write to an eval file until a Skill call named exactly `claude-api` with args `build-eval`, or the `/claude-api build-eval` command, appears in the transcript.
 - `blocking/merge_review_gate.py` denies an agent's merge until a review pass on the merged head reported zero findings, or ruled out every finding and linked the posted rulings. It reads the receipt `scripts/merge_review_receipt.py` writes, requires the merge, auto-merge or merge-queue entry to be pinned to that head, and skips repositories listed in `CLAUDE_MERGE_REVIEW_EXEMPT_REPOSITORIES`. Its deny reason names the review command `CLAUDE_MERGE_REVIEW_COMMAND` sets. The reason tells the agent to run that command for the first three passes and `/code-review low --fix <number>` for each later pass; the gate itself counts no passes.
@@ -39,6 +40,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
+- `blocking/resolve_thread_reply_gate.py` runs on `PreToolUse`, matcher `mcp__.*__resolve_review_thread`, timeout `10` seconds in `hooks.json`.
 - `blocking/verify_before_commit_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell`, timeout `30` seconds in `hooks.json`.
 - `blocking/build_eval_before_eval_write_gate.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|apply_patch`, timeout `10` seconds in `hooks.json`.
 - `blocking/merge_review_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(merge_pull_request|enable_pr_auto_merge)`, timeout `10` seconds in `hooks.json`.
@@ -53,6 +55,7 @@ Preconditions:
 - Run each command from the repository root with Python and pytest available. The tests create transcript and payload fixtures.
 
 - **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
+- **Resolve reply.** Input is a transcript where a thread reply came back refused, or with no reply, or with one reply already spent on a resolve, then a resolve call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_resolve_thread_reply_gate.py -q`. The adjacent test observes a deny whose reason says to post the reply, confirm it posted, then resolve. A reply that posted before the resolve passes, and an unreadable transcript passes.
 - **Final reply.** Input is a closing reply that says "My guess is one to two hours." or cites a run no tool result shows. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_final_reply_gate.py -q`. The adjacent test observes a `block` decision that quotes the sentence or the citation; a reply that cites a run a tool result shows passes. A reply with a plain-text `D:\Reports\.claude\report.html` is blocked; the same path in backticks or a fenced block passes.
 - **Open tasks.** Input is a session whose task list still has "rotate the deploy key" pending and a closing reply of "Done.". Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_open_tasks_stop_gate.py -q`. The adjacent test observes a `block` decision that names the item; a reply line `Blocked: rotate the deploy key - <what the user must give>` passes. The same file covers an interrupted ask, a continuation plan list that leaves items out, `Done:` and `Dropped:` lines, and a carried item that a later list marks completed.
 - **Ask recorder.** Input is a `UserPromptSubmit` payload with a work prompt, a question, a `<task-notification>` envelope, and a polite request. Run `python -m pytest packages/claude-dev-env/hooks/session/test_open_task_ask_recorder.py -q`. The adjacent test observes `ask-1` and `ask-2` for the work prompt and the request, no ask for the other two, and empty stdout.

package/hooks/hooks.json

@@ -102,6 +102,16 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__.*__resolve_review_thread",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/resolve_thread_reply_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Bash|PowerShell",
         "hooks": [

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -9,6 +9,7 @@ __all__ = [
     "ARTIFACT_QUICKSTART_ACTION",
     "ARTIFACT_TEMPLATE_PATH",
     "ARTIFACT_TOOL_NAME",
+    "PACKAGE_ROOT_DIRECTORY",
     "HTML_PLAN_TEMPLATE_README_PATH",
     "POINTER_TEXT_TEMPLATE",
     "SKILL_NAME_INPUT_KEY",
@@ -23,7 +24,8 @@ ARTIFACT_QUICKSTART_ACTION = "quickstart"
 SKILL_TOOL_NAME = "Skill"
 SKILL_NAME_INPUT_KEY = "skill"
 ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
-TEMPLATES_DIRECTORY = Path(__file__).resolve().parents[2] / "docs" / "templates"
+PACKAGE_ROOT_DIRECTORY = Path(__file__).resolve().parents[2]
+TEMPLATES_DIRECTORY = PACKAGE_ROOT_DIRECTORY / "docs" / "templates"
 ARTIFACT_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "README.md"
 HTML_PLAN_TEMPLATE_README_PATH = TEMPLATES_DIRECTORY / "html-plan" / "README.md"
 STATUS_FLOWCHART_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "status-flowchart.html"

package/hooks/hooks_constants/open_tasks_stop_gate_constants.py

@@ -69,6 +69,30 @@ BLOCK_REASON_SUFFIX = (
     "\nKeep working each one now. End the reply with one line per item you cannot finish this turn:"
     " 'Blocked: <item> - <what the user must give>' when only the user can unblock it, or"
     " 'Open: <item> - <the step you take next>' when you are still working it."
+    " When the user must decide, choose, or approve, ask on a question card (AskUserQuestion,"
+    " or mcp__hearthbot__ask_decision / request_decision) this turn, then add the Blocked line."
+)
+BLOCKED_REPORT_KIND = "blocked"
+REPORT_KIND_GROUP_INDEX = 1
+DECISION_WORD_PATTERN = (
+    r"\b(?:ok|okay|approve[sd]?|approval|go-?ahead|green\s+light|sign-?off|decide[sd]?|decision"
+    r"|choose|choice|permission|consent|say-?so|your\s+call|prefer(?:s|ence)?)\b"
+)
+DECISION_CARD_TOOL_PATTERN = (
+    r"(?:^|__)AskUserQuestion$|hearthbot__(?:ask|request)_decision$|^request_user_input(?:_async)?$"
+)
+ALL_SKIPPED_PROMPT_FLAGS = ("isMeta", "isSidechain", "isCompactSummary")
+USER_ROLE = "user"
+USER_RECORD_TYPE = "user"
+CODEX_MESSAGE_TYPE = "message"
+CODEX_CARD_EVENT = "card"
+CODEX_PROMPT_EVENT = "prompt"
+STOP_HOOK_FEEDBACK_PREFIX = "Stop hook feedback"
+DECISION_LINE_TEMPLATE = "\n- {line}"
+DECISION_BLOCK_REASON_PREFIX = "This reply asks the user for a decision in a Blocked line, with no question card this turn:"
+DECISION_BLOCK_REASON_SUFFIX = (
+    "\nPut the decision on a question card now: call AskUserQuestion, or mcp__hearthbot__ask_decision or"
+    " mcp__hearthbot__request_decision, with two or three choices. Then end the reply with the Blocked line."
 )
 ASK_CLOSE_SUFFIX = (
     "\nClose a finished ask with a 'Done: #ask-N' line. Close an ask or a carried plan item the user"

package/hooks/hooks_constants/pr_lifecycle_skill_gate_constants.py

@@ -32,12 +32,21 @@ SEPARATOR_PIECE = "separator"
 COMMENT_PIECE = "comment"
 LINE_CONTINUATION_PIECE = "continuation"
 UNCLOSED_QUOTE_PIECE = "unclosed"
+DOUBLE_QUOTE = '"'
+LINE_END = "\n"
+ESCAPED_CHARACTER_GROUP = 1
+DOUBLE_QUOTED_ESCAPE_PATTERN = re.compile(r"\\(.)", re.DOTALL)
+ALL_PIECE_REPLACEMENT_TEXTS: dict[str | None, str] = {
+    SEPARATOR_PIECE: SEGMENT_BREAK,
+    COMMENT_PIECE: REMOVED_TEXT,
+    LINE_CONTINUATION_PIECE: REMOVED_TEXT,
+}
 COMMAND_PIECE_PATTERN = re.compile(
     r"'[^']*'"
     r'|"(?:\\.|[^"\\])*"'
     rf"|(?P<{LINE_CONTINUATION_PIECE}>\\\n)"
     rf"|\\.[^{re.escape(COMMAND_WHITESPACE + COMMAND_SEPARATORS)}'\"\\]*"
-    rf"|(?P<{COMMENT_PIECE}>(?<![^{re.escape(COMMAND_WHITESPACE + COMMAND_SEPARATORS)}])(?<!\\\n)#[^\n]*)"
+    rf"|(?P<{COMMENT_PIECE}>(?<![^{re.escape(COMMAND_WHITESPACE + COMMAND_SEPARATORS)}])#[^\n]*)"
     rf"|(?P<{SEPARATOR_PIECE}>[{re.escape(COMMAND_SEPARATORS)}])"
     rf"|(?P<{UNCLOSED_QUOTE_PIECE}>['\"])"
     r"|.",

package/hooks/hooks_constants/resolve_thread_reply_gate_constants.py

@@ -0,0 +1,22 @@
+"""Constants for the gate that holds a review thread resolve until a reply on it posts."""
+
+import re
+
+from hooks_constants.reply_length_gate_constants import (
+    MAXIMUM_SENTENCE_COUNT,
+    MAXIMUM_WORDS_PER_SENTENCE,
+)
+
+RESOLVE_TOOL_NAME_PATTERN = re.compile(r"^mcp__.+__resolve_review_thread$")
+ALL_REPLY_TOOL_NAME_SUFFIXES = ("__add_reply_to_pull_request_comment",)
+SHELL_COMMAND_KEY = "command"
+SHELL_REPLY_COMMAND_PATTERN = re.compile(
+    r"\bgh\s+api\b.*(?:/comments/\d+/replies\b|addPullRequestReviewThreadReply)", re.DOTALL
+)
+MISSING_REPLY_REASON = (
+    "This review thread has no reply that posted since the last user prompt and the last resolve."
+    " Post the reply with add_reply_to_pull_request_comment, confirm its result came back without"
+    " an error, then resolve the thread. A reply that a hook refused did not post; shorten it to"
+    f" at most {MAXIMUM_SENTENCE_COUNT} sentences of at most {MAXIMUM_WORDS_PER_SENTENCE} words each,"
+    " footer included, and send it again."
+)

package/hooks/hooks_constants/test_artifact_template_pointer_constants.py

@@ -47,3 +47,15 @@ def test_every_exported_name_resolves_to_a_module_attribute() -> None:
     ]
 
     assert all_missing_names == []
+
+
+def test_every_template_path_sits_under_the_package_root() -> None:
+    package_root = artifact_template_pointer_constants.PACKAGE_ROOT_DIRECTORY
+
+    assert (package_root / "hooks" / "hooks_constants").is_dir()
+    for each_path in (
+        artifact_template_pointer_constants.ARTIFACT_TEMPLATE_PATH,
+        artifact_template_pointer_constants.HTML_PLAN_TEMPLATE_README_PATH,
+        artifact_template_pointer_constants.STATUS_FLOWCHART_TEMPLATE_PATH,
+    ):
+        assert each_path.relative_to(package_root).parts[:2] == ("docs", "templates")

package/hooks/hooks_constants/transcript_skill_scan_constants.py

@@ -8,3 +8,5 @@ USER_ENTRY_TYPE = "user"
 COMMAND_ARGUMENTS_PATTERN = r"<command-args>(.*?)</command-args>"
 META_ENTRY_FIELD = "isMeta"
 TOOL_RESULT_BLOCK_TYPE = "tool_result"
+IS_ERROR_FIELD = "is_error"
+TOOL_USE_ID_FIELD = "tool_use_id"

package/hooks/session/artifact_template_pointer.py

@@ -37,6 +37,7 @@ from hooks_constants.artifact_template_pointer_constants import (
     ARTIFACT_TEMPLATE_PATH,
     ARTIFACT_TOOL_NAME,
     HTML_PLAN_TEMPLATE_README_PATH,
+    PACKAGE_ROOT_DIRECTORY,
     POINTER_TEXT_TEMPLATE,
     SKILL_NAME_INPUT_KEY,
     SKILL_TOOL_NAME,
@@ -53,6 +54,28 @@ from hooks_constants.spawn_readiness_hook_constants import (
     TOOL_INPUT_KEY,
     TOOL_NAME_KEY,
 )
+from open_task_asks import claude_home
+
+
+def installed_template_path(package_template_path: Path) -> Path:
+    """Return the template path that exists where this hook runs.
+
+    A source checkout keeps ``docs`` beside ``hooks``. An install puts hooks
+    under the agents home and docs under the Claude home, so the same relative
+    path is read from the Claude home there::
+
+        <checkout>/packages/claude-dev-env/docs/templates/x.md  -> kept
+        ~/.agents/docs/templates/x.md (missing)                 -> ~/.claude/docs/templates/x.md
+
+    Args:
+        package_template_path: A template path under the package root.
+
+    Returns:
+        The package path when it exists, else the same relative path under the Claude home.
+    """
+    if package_template_path.exists():
+        return package_template_path
+    return claude_home() / package_template_path.relative_to(PACKAGE_ROOT_DIRECTORY)
 
 
 def starts_an_artifact_page(tool_name: object, tool_input: object) -> bool:
@@ -85,9 +108,9 @@ def decide_hook_output(all_hook_fields: dict[str, object]) -> dict[str, object]
         HOOK_SPECIFIC_OUTPUT_KEY: {
             HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
             ADDITIONAL_CONTEXT_KEY: POINTER_TEXT_TEMPLATE.format(
-                path_of_status_flowchart=STATUS_FLOWCHART_TEMPLATE_PATH,
-                path_of_plan_readme=HTML_PLAN_TEMPLATE_README_PATH,
-                path_of_page_readme=ARTIFACT_TEMPLATE_PATH,
+                path_of_status_flowchart=installed_template_path(STATUS_FLOWCHART_TEMPLATE_PATH),
+                path_of_plan_readme=installed_template_path(HTML_PLAN_TEMPLATE_README_PATH),
+                path_of_page_readme=installed_template_path(ARTIFACT_TEMPLATE_PATH),
             ),
         }
     }

package/hooks/session/test_artifact_template_pointer.py

@@ -3,6 +3,8 @@ import subprocess
 import sys
 from pathlib import Path
 
+import pytest
+
 _SESSION_DIR = Path(__file__).resolve().parent
 _HOOKS_ROOT = _SESSION_DIR.parent
 for each_sys_path_entry in (str(_SESSION_DIR), str(_HOOKS_ROOT)):
@@ -99,3 +101,17 @@ def test_empty_stdin_stays_quiet() -> None:
         [sys.executable, str(HOOK_SCRIPT)], input="", capture_output=True, text=True, check=True
     )
     assert completed.stdout == ""
+
+
+def test_installed_template_path_should_keep_a_package_path_that_exists() -> None:
+    assert artifact_template_pointer.installed_template_path(ARTIFACT_TEMPLATE_PATH) == ARTIFACT_TEMPLATE_PATH
+
+
+def test_installed_template_path_should_read_the_claude_home_when_the_package_path_is_missing(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv("CLAUDE_CONFIG_DIR", str(tmp_path))
+    missing_package_path = artifact_template_pointer.PACKAGE_ROOT_DIRECTORY / "docs" / "templates" / "absent" / "README.md"
+    assert artifact_template_pointer.installed_template_path(missing_package_path) == (
+        tmp_path / "docs" / "templates" / "absent" / "README.md"
+    )