claude-dev-env 8.98.4 → 8.98.6

package/hooks/blocking/open_tasks_stop_gate.py

@@ -15,7 +15,7 @@ An item with status ``pending`` or ``in_progress`` is open, and so is an ask
 until a reply closes it. The turn may end only when the closing reply names
 every open item on a report line::
 
-    allow: Blocked: Rotate the deploy key - the owner must approve the org secret
+    allow: Blocked: Rotate the deploy key - the owner pastes the org secret
     allow: - Open: #3 - waits on the release checks
     allow: Open: #ask-2 - the export job runs next
     block: (reply never mentions "Rotate the deploy key")
@@ -30,6 +30,22 @@ of the session close an item for good::
 A ``Dropped:`` quote must appear in a prompt the user sent after that ask, or
 after the last plan list that held the item.
 
+A ``Blocked:`` line that asks the user for a decision needs a question card
+in the same turn. The gate calls a line a decision when it holds a decision
+word: ok, okay, approve, approval, go-ahead, green light, sign-off, decide,
+decision, choose, choice, permission, consent, say-so, your call, or prefer.
+Any other ``Blocked:`` line names an input the user
+supplies, such as a secret, a file, or a step on a device, and needs no card::
+
+    block: Blocked: #ask-1 - your OK to merge the app branch first  (no card this turn)
+    allow: the same line after an AskUserQuestion call this turn
+    allow: Blocked: #ask-1 - the new deploy key secret, pasted into the session
+
+The cards are ``AskUserQuestion``, ``mcp__hearthbot__ask_decision``,
+``mcp__hearthbot__request_decision``, and Codex ``request_user_input``. The
+check runs whether or not any item is open. A Cursor payload skips it, because
+the gate reads no card call from a Cursor transcript.
+
 A block sends the open items back as the reason, so the model keeps working or
 reports them. Claude Code ends the turn after eight blocks in a row. Codex
 turns the reason into a continuation prompt. A Cursor payload (it carries
@@ -61,7 +77,7 @@ if blocking_directory not in sys.path:
 from hooks_constants.hook_block_logger import log_hook_block
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from open_task_asks import RecordedPrompt, claude_home, recorded_prompts
-from open_tasks_transcript import TaskItem, normalized_text, parsed_object, replayed_transcript
+from open_tasks_transcript import TaskItem, TranscriptReplay, normalized_text, parsed_object, replayed_transcript
 from hooks_constants.open_tasks_stop_gate_constants import (
     ALLOW_EXIT_CODE,
     ASK_CLOSE_SUFFIX,
@@ -73,13 +89,18 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     BLOCK_DECISION,
     BLOCK_REASON_PREFIX,
     BLOCK_REASON_SUFFIX,
+    BLOCKED_REPORT_KIND,
     CURSOR_COMPLETED_STATUS,
     CURSOR_CONVERSATION_ID_KEY,
     CURSOR_FOLLOWUP_LIMIT,
     CURSOR_FOLLOWUP_MESSAGE_KEY,
     CURSOR_LOOP_COUNT_KEY,
     CURSOR_STATUS_KEY,
+    DECISION_BLOCK_REASON_PREFIX,
+    DECISION_BLOCK_REASON_SUFFIX,
     DECISION_KEY,
+    DECISION_LINE_TEMPLATE,
+    DECISION_WORD_PATTERN,
     DONE_LINE_PATTERN,
     DONE_TEXT_GROUP_INDEX,
     DROPPED_LINE_PATTERN,
@@ -91,7 +112,9 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     LAST_ASSISTANT_MESSAGE_KEY,
     PENDING_STATUS,
     REASON_KEY,
+    REPORT_KIND_GROUP_INDEX,
     REPORT_LINE_PATTERN,
+    REPLY_TEXT_SEPARATOR,
     REPORTED_TEXT_GROUP_INDEX,
     SESSION_ID_KEY,
     TASK_FILE_GLOB,
@@ -226,12 +249,28 @@ def deduplicated_by_subject(all_sources: list[list[TaskItem]]) -> list[TaskItem]
     return all_kept_items
 
 
-def unreported_open_items(all_hook_input_fields: dict[str, object]) -> list[TaskItem]:
+def closing_reply_text(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> str:
+    """Return the closing reply from the hook input, or the last assistant text of the transcript."""
+    reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
+    return reply_value if isinstance(reply_value, str) else replay.last_assistant_text
+
+
+def uncarded_decision_lines(reply_text: str, replay: TranscriptReplay) -> list[str]:
+    """Return each ``Blocked:`` line that asks for a decision when no question card ran this turn."""
+    if replay.has_turn_decision_card:
+        return []
+    return [
+        each_match.group(0).strip()
+        for each_match in _line_matches(REPORT_LINE_PATTERN, [reply_text])
+        if each_match.group(REPORT_KIND_GROUP_INDEX).lower() == BLOCKED_REPORT_KIND
+        and re.search(DECISION_WORD_PATTERN, each_match.group(REPORTED_TEXT_GROUP_INDEX), re.IGNORECASE)
+    ]
+
+
+def unreported_open_items(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> list[TaskItem]:
     """Return the open task items and asks the closing reply does not report."""
-    replay = replayed_transcript(all_hook_input_fields.get(TRANSCRIPT_PATH_KEY))
     session_id = all_hook_input_fields.get(SESSION_ID_KEY)
-    reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
-    reply_text = reply_value if isinstance(reply_value, str) else replay.last_assistant_text
+    reply_text = closing_reply_text(all_hook_input_fields, replay)
     all_closing_texts = [*replay.all_assistant_texts, reply_text]
     all_prompts = recorded_prompts(session_id)
     all_replayed_items = [
@@ -256,6 +295,12 @@ def _item_line(task_item: TaskItem) -> str:
     return ITEM_LINE_TEMPLATE.format(subject=task_item.subject or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=task_item.item_id))
 
 
+def decision_block_reason_for(all_decision_lines: list[str]) -> str:
+    """Return the block reason that quotes each decision line and names the question card."""
+    all_quoted_lines = "".join(DECISION_LINE_TEMPLATE.format(line=each_line) for each_line in all_decision_lines)
+    return DECISION_BLOCK_REASON_PREFIX + all_quoted_lines + DECISION_BLOCK_REASON_SUFFIX
+
+
 def block_reason_for(all_open_items: list[TaskItem]) -> str:
     """Return the block reason that lists each open item, and how to close an ask when one is open."""
     has_open_ask = any(each_item.item_id.startswith(ASK_ID_PREFIX) for each_item in all_open_items)
@@ -295,10 +340,18 @@ def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None or is_unfinished_cursor_stop(hook_input) or has_spent_cursor_followups(hook_input):
         return ALLOW_EXIT_CODE
-    all_open_items = unreported_open_items(hook_input)
-    if not all_open_items:
+    replay = replayed_transcript(hook_input.get(TRANSCRIPT_PATH_KEY))
+    all_open_items = unreported_open_items(hook_input, replay)
+    all_decision_lines = (
+        [] if hook_input.get(CURSOR_CONVERSATION_ID_KEY) else uncarded_decision_lines(closing_reply_text(hook_input, replay), replay)
+    )
+    if not all_open_items and not all_decision_lines:
         return ALLOW_EXIT_CODE
-    block_reason = block_reason_for(all_open_items)
+    all_reason_parts = [
+        *([block_reason_for(all_open_items)] if all_open_items else []),
+        *([decision_block_reason_for(all_decision_lines)] if all_decision_lines else []),
+    ]
+    block_reason = REPLY_TEXT_SEPARATOR.join(all_reason_parts)
     reply_value = hook_input.get(LAST_ASSISTANT_MESSAGE_KEY)
     log_hook_block(
         Path(__file__).name,

package/hooks/blocking/open_tasks_transcript.py

@@ -17,6 +17,16 @@ A desktop plan call either lists items or moves the current list::
 Only ``assistant`` records count for a desktop plan call, because Claude Code
 also copies each call into ``api-request-blob`` records.
 
+The replay also notes whether the current turn called a question card::
+
+    AskUserQuestion, mcp__hearthbot__ask_decision, mcp__hearthbot__request_decision   (Claude Code)
+    request_user_input, request_user_input_async                                       (Codex)
+
+A turn starts at the last user prompt record. A tool result, a record flagged
+``isMeta``, ``isSidechain`` or ``isCompactSummary``, and a ``Stop hook feedback``
+message do not start a turn; these are the flags session_title_turn_gate.py
+skips, and its tests model Stop hook feedback as an ``isMeta`` user record.
+
 The Cursor CLI can also reach TodoWrite through ``CallDynamicTool``, with the
 TodoWrite input under ``arguments``; that call counts as the TodoWrite call.
 """
@@ -35,6 +45,7 @@ if hooks_root_directory not in sys.path:
     sys.path.insert(0, hooks_root_directory)
 
 from hooks_constants.open_tasks_stop_gate_constants import (
+    ALL_SKIPPED_PROMPT_FLAGS,
     ASSISTANT_RECORD_TYPE,
     ASSISTANT_ROLE,
     CCD_PLAN_ADVANCE_KEY,
@@ -45,15 +56,19 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     CCD_PLAN_START_KEY,
     CCD_PLAN_TOOL_NAME,
     CODEX_ARGUMENTS_KEY,
+    CODEX_CARD_EVENT,
     CODEX_FUNCTION_CALL_TYPE,
+    CODEX_MESSAGE_TYPE,
     CODEX_PAYLOAD_KEY,
     CODEX_PLAN_KEY,
     CODEX_PLAN_TOOL_NAME,
+    CODEX_PROMPT_EVENT,
     CODEX_RESPONSE_ITEM_TYPE,
     CODEX_STEP_KEY,
     COMPLETED_STATUS,
     CONTENT_KEY,
     CREATED_TASK_ID_GROUP_INDEX,
+    DECISION_CARD_TOOL_PATTERN,
     DYNAMIC_TOOL_ARGUMENTS_KEY,
     DYNAMIC_TOOL_CALL_NAME,
     DYNAMIC_TOOL_NAME_KEY,
@@ -66,6 +81,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     RECORD_TYPE_KEY,
     REPLY_TEXT_SEPARATOR,
     ROLE_KEY,
+    STOP_HOOK_FEEDBACK_PREFIX,
     TASK_CREATED_PATTERN,
     TASK_CREATE_TOOL_NAME,
     TASK_ID_KEY,
@@ -86,6 +102,8 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     TOOL_USE_ID_KEY,
     UTC_OFFSET_TEXT,
     UTC_SUFFIX,
+    USER_RECORD_TYPE,
+    USER_ROLE,
     UTF8_ENCODING,
     WORD_SEPARATOR,
 )
@@ -164,6 +182,47 @@ def _result_text(all_block_fields: dict[str, object]) -> str:
     )
 
 
+def is_decision_card_tool(tool_name: object) -> bool:
+    """Return True for a tool that puts a question card in front of the user."""
+    return isinstance(tool_name, str) and re.search(DECISION_CARD_TOOL_PATTERN, tool_name) is not None
+
+
+def is_user_prompt_record(all_record_fields: dict[str, object]) -> bool:
+    """Return True for a record that holds a prompt the user sent, which starts a new turn."""
+    message_body = all_record_fields.get(MESSAGE_KEY)
+    message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
+    if USER_RECORD_TYPE != all_record_fields.get(RECORD_TYPE_KEY) and USER_ROLE not in (all_record_fields.get(ROLE_KEY), message_role):
+        return False
+    if any(all_record_fields.get(each_flag) for each_flag in ALL_SKIPPED_PROMPT_FLAGS):
+        return False
+    content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
+    if isinstance(content_value, str):
+        prompt_text = content_value
+    else:
+        all_blocks = _content_blocks(all_record_fields)
+        if any(each_block.get(RECORD_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE for each_block in all_blocks):
+            return False
+        if any(each_block.get(RECORD_TYPE_KEY) != TEXT_KEY for each_block in all_blocks):
+            return True
+        prompt_text = WORD_SEPARATOR.join(
+            str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if each_block.get(RECORD_TYPE_KEY) == TEXT_KEY
+        )
+    return bool(prompt_text.strip()) and not prompt_text.lstrip().startswith(STOP_HOOK_FEEDBACK_PREFIX)
+
+
+def codex_turn_event(all_record_fields: dict[str, object]) -> str | None:
+    """Return ``card`` for a Codex question card call, ``prompt`` for a Codex user message, else None."""
+    payload_body = all_record_fields.get(CODEX_PAYLOAD_KEY)
+    if all_record_fields.get(RECORD_TYPE_KEY) != CODEX_RESPONSE_ITEM_TYPE or not isinstance(payload_body, dict):
+        return None
+    payload_type = payload_body.get(RECORD_TYPE_KEY)
+    if payload_type == CODEX_FUNCTION_CALL_TYPE and is_decision_card_tool(payload_body.get(TOOL_NAME_KEY)):
+        return CODEX_CARD_EVENT
+    if payload_type == CODEX_MESSAGE_TYPE and payload_body.get(ROLE_KEY) == USER_ROLE:
+        return CODEX_PROMPT_EVENT
+    return None
+
+
 def _numbered_items(all_entries: object, subject_key: str) -> list[TaskItem]:
     if not isinstance(all_entries, list):
         return []
@@ -245,7 +304,7 @@ def unwrapped_tool_call(tool_name: str, all_input_fields: dict[str, object]) ->
     return inner_name, all_inner_arguments
 
 
-class _TranscriptReplay:
+class TranscriptReplay:
     """Fold transcript records into the newest task list they describe."""
 
     def __init__(self) -> None:
@@ -256,8 +315,15 @@ class _TranscriptReplay:
         self.own_plan_count = 0
         self.last_assistant_text = ""
         self.all_assistant_texts: list[str] = []
+        self.has_turn_decision_card = False
 
     def apply_record(self, all_record_fields: dict[str, object]) -> None:
+        codex_event = codex_turn_event(all_record_fields)
+        if codex_event is not None:
+            self.has_turn_decision_card = codex_event == CODEX_CARD_EVENT
+            return
+        if is_user_prompt_record(all_record_fields):
+            self.has_turn_decision_card = False
         plan_items = codex_plan_items(all_record_fields)
         if plan_items is not None:
             self.latest_items = plan_items
@@ -266,6 +332,8 @@ class _TranscriptReplay:
         is_assistant_record = all_record_fields.get(RECORD_TYPE_KEY) == ASSISTANT_RECORD_TYPE
         for each_block in all_blocks:
             plan_input = each_block.get(TOOL_INPUT_KEY)
+            if is_assistant_record and each_block.get(RECORD_TYPE_KEY) == TOOL_USE_BLOCK_TYPE and is_decision_card_tool(each_block.get(TOOL_NAME_KEY)):
+                self.has_turn_decision_card = True
             if is_assistant_record and each_block.get(TOOL_NAME_KEY) == CCD_PLAN_TOOL_NAME and isinstance(plan_input, dict):
                 self.apply_desktop_plan(plan_input, record_epoch(all_record_fields))
             else:
@@ -364,9 +432,9 @@ class _TranscriptReplay:
         return [each_item for each_source in all_present_sources for each_item in each_source]
 
 
-def replayed_transcript(transcript_path: object) -> _TranscriptReplay:
+def replayed_transcript(transcript_path: object) -> TranscriptReplay:
     """Fold every transcript record into one replay of the task list and the last assistant text."""
-    replay = _TranscriptReplay()
+    replay = TranscriptReplay()
     for each_record in _transcript_records(transcript_path):
         replay.apply_record(each_record)
     return replay

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -19,6 +19,7 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     ALL_API_ACTION_NAMES,
     ALL_COMMAND_PREFIX_WORDS,
     ALL_GITHUB_MCP_TOOL_SUFFIXES,
+    ALL_PIECE_REPLACEMENT_TEXTS,
     ALL_PREFIX_OPTIONS_WITH_VALUE,
     ALL_PYTHON_EXECUTABLES,
     ALL_SHELL_WRAPPER_EXECUTABLES,
@@ -28,16 +29,19 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     BUILD_EVAL_COMMAND_MARKER,
     COMMAND_PIECE_PATTERN,
     COMMAND_WHITESPACE,
-    COMMENT_PIECE,
     DENY_DECISION,
     DENY_REASON,
+    DOUBLE_QUOTE,
+    DOUBLE_QUOTED_ESCAPE_PATTERN,
     ENVIRONMENT_ASSIGNMENT_PATTERN,
+    ESCAPED_CHARACTER_GROUP,
     GH_API_COMMAND,
     GH_PULL_REQUEST_COMMAND,
     GIT_ACTIONS,
     GIT_GLOBAL_OPTIONS_WITH_VALUE,
     HOOK_EVENT_NAME,
     LINE_CONTINUATION_PIECE,
+    LINE_END,
     MERGE_PATH_SUFFIX,
     NO_COMMENT_CHARACTERS,
     OPTION_AND_VALUE_WORD_COUNT,
@@ -47,7 +51,6 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
     PYTHON_OPTIONS_WITH_VALUE,
     REMOVED_TEXT,
     SEGMENT_BREAK,
-    SEPARATOR_PIECE,
     SESSION_TRANSCRIPT_PATH_FIELD,
     SHELL_TOOL_NAMES,
     SKILL_NAME,
@@ -77,6 +80,32 @@ from transcript_skill_scan import (
 )
 
 
+def _joined_piece_text(piece: re.Match[str]) -> str:
+    """Return one command piece with its backslash-newline line continuations removed.
+
+    ::
+
+        \\<newline>          ->  ""
+        "gi\\<newline>t"     ->  "git"
+        'gi\\<newline>t'     ->  unchanged
+
+    Args:
+        piece: One match of ``COMMAND_PIECE_PATTERN`` on the raw command.
+
+    Returns:
+        The piece text as bash reads it after joining continuations.
+    """
+    if piece.lastgroup == LINE_CONTINUATION_PIECE:
+        return REMOVED_TEXT
+    if piece.group().startswith(DOUBLE_QUOTE):
+        return DOUBLE_QUOTED_ESCAPE_PATTERN.sub(_without_line_continuation, piece.group())
+    return piece.group()
+
+
+def _without_line_continuation(escape: re.Match[str]) -> str:
+    return REMOVED_TEXT if escape.group(ESCAPED_CHARACTER_GROUP) == LINE_END else escape.group()
+
+
 def _unquoted_segment_texts(command: str) -> list[str] | None:
     """Split a command at each separator outside quotes, escapes, and comments.
 
@@ -91,16 +120,13 @@ def _unquoted_segment_texts(command: str) -> list[str] | None:
     Returns:
         The raw text of each segment in order, or None when a quote never closes.
     """
-    all_pieces = list(COMMAND_PIECE_PATTERN.finditer(command))
-    if any(each_piece.lastgroup == UNCLOSED_QUOTE_PIECE for each_piece in all_pieces):
+    all_raw_pieces = list(COMMAND_PIECE_PATTERN.finditer(command))
+    if any(each_piece.lastgroup == UNCLOSED_QUOTE_PIECE for each_piece in all_raw_pieces):
         return None
-    all_replacement_texts: dict[str | None, str] = {
-        SEPARATOR_PIECE: SEGMENT_BREAK,
-        COMMENT_PIECE: REMOVED_TEXT,
-        LINE_CONTINUATION_PIECE: REMOVED_TEXT,
-    }
+    joined_command = REMOVED_TEXT.join(_joined_piece_text(each_piece) for each_piece in all_raw_pieces)
+    all_pieces = list(COMMAND_PIECE_PATTERN.finditer(joined_command))
     marked_command = REMOVED_TEXT.join(
-        all_replacement_texts.get(each_piece.lastgroup, each_piece.group()) for each_piece in all_pieces
+        ALL_PIECE_REPLACEMENT_TEXTS.get(each_piece.lastgroup, each_piece.group()) for each_piece in all_pieces
     )
     return marked_command.split(SEGMENT_BREAK)
 

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/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/package.json

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