claude-dev-env 8.98.8 → 8.98.10

package/hooks/blocking/resolve_thread_reply_gate.py

@@ -1,9 +1,10 @@
-"""Deny a review thread resolve until a reply posted after the last user prompt and the last resolve."""
+"""Deny a review thread resolve until a reply on that thread posted after the last user prompt and its last resolve."""
 
 from __future__ import annotations
 
+import json
 import sys
-from collections.abc import Iterable
+from collections.abc import Iterable, Iterator
 from pathlib import Path
 
 hooks_directory = str(Path(__file__).resolve().parent.parent)
@@ -15,12 +16,25 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
 from hooks_constants.pre_tool_use_stdin import print_decision_from_stdin
 from hooks_constants.resolve_thread_reply_gate_constants import (
     ALL_REPLY_TOOL_NAME_SUFFIXES,
+    ALL_THREAD_ID_INPUT_KEYS,
+    COMMENT_ANCHOR_PATTERN,
+    COMMENT_ID_INPUT_KEY,
     MISSING_REPLY_REASON,
     RESOLVE_TOOL_NAME_PATTERN,
+    RESOLVE_THREAD_METHOD,
+    REVIEW_WRITE_METHOD_KEY,
+    REVIEW_WRITE_TOOL_NAME_PATTERN,
     SHELL_COMMAND_KEY,
     SHELL_REPLY_COMMAND_PATTERN,
+    SHELL_REPLY_COMMENT_ID_PATTERN,
+    SHELL_RESOLVE_COMMAND_PATTERN,
+    SHELL_RESOLVE_COMMENT_ID_PATTERN,
+    TEXT_BLOCK_TYPE,
+    TEXT_FIELD,
+    THREAD_ID_PATTERN,
 )
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from hooks_constants.transcript_skill_scan_constants import IS_ERROR_FIELD, TOOL_RESULT_BLOCK_TYPE
 from transcript_skill_scan import TranscriptToolCall, tool_calls_since_last_prompt
 
 
@@ -33,6 +47,51 @@ def is_resolve_call(tool_name: object) -> bool:
     return isinstance(tool_name, str) and RESOLVE_TOOL_NAME_PATTERN.match(tool_name) is not None
 
 
+def _is_review_write_resolve(tool_name: object, all_tool_input_fields: dict[str, object]) -> bool:
+    return (
+        isinstance(tool_name, str)
+        and REVIEW_WRITE_TOOL_NAME_PATTERN.match(tool_name) is not None
+        and all_tool_input_fields.get(REVIEW_WRITE_METHOD_KEY) == RESOLVE_THREAD_METHOD
+    )
+
+
+def _shell_command(tool_name: object, all_tool_input_fields: dict[str, object]) -> str | None:
+    command = all_tool_input_fields.get(SHELL_COMMAND_KEY)
+    return command if tool_name in SHELL_TOOL_NAMES and isinstance(command, str) else None
+
+
+def resolved_thread_ids(tool_name: object, all_tool_input_fields: dict[str, object]) -> frozenset[str] | None:
+    """Return the thread ids or comment ids a call resolves, or None when the call resolves no review thread.
+
+    ::
+
+        mcp__github__resolve_review_thread {"threadID": "PRRT_a"}  -> {"PRRT_a"}
+        mcp__github__pull_request_review_write
+            {"method": "resolve_thread", "threadId": "PRRT_a"}     -> {"PRRT_a"}
+        Bash "gh api graphql ... resolveReviewThread ... PRRT_a"   -> {"PRRT_a"}
+        Bash "gh api graphql ... resolveReviewThread ... $thread"  -> {}
+        Bash "gh api -X POST .../pulls/7/ccr/comments/9/resolve"   -> {"9"}
+        Bash "gh pr view 7"                                        -> None
+
+    Args:
+        tool_name: The tool name from a hook payload or transcript.
+        all_tool_input_fields: The tool input from a hook payload or transcript.
+    """
+    if is_resolve_call(tool_name) or _is_review_write_resolve(tool_name, all_tool_input_fields):
+        return frozenset(
+            each_value
+            for each_value in (all_tool_input_fields.get(each_key) for each_key in ALL_THREAD_ID_INPUT_KEYS)
+            if isinstance(each_value, str) and each_value
+        )
+    command = _shell_command(tool_name, all_tool_input_fields)
+    if command is None:
+        return None
+    all_resolved_comment_ids = frozenset(SHELL_RESOLVE_COMMENT_ID_PATTERN.findall(command))
+    if not all_resolved_comment_ids and SHELL_RESOLVE_COMMAND_PATTERN.search(command) is None:
+        return None
+    return frozenset(THREAD_ID_PATTERN.findall(command)) | all_resolved_comment_ids
+
+
 def is_reply_call(tool_call: TranscriptToolCall) -> bool:
     """Return whether a transcript tool call replies on a review thread.
 
@@ -48,66 +107,165 @@ def is_reply_call(tool_call: TranscriptToolCall) -> bool:
     """
     if tool_call.name.endswith(ALL_REPLY_TOOL_NAME_SUFFIXES):
         return True
-    command = tool_call.tool_input.get(SHELL_COMMAND_KEY)
-    return (
-        tool_call.name in SHELL_TOOL_NAMES
-        and isinstance(command, str)
-        and SHELL_REPLY_COMMAND_PATTERN.search(command) is not None
-    )
+    command = _shell_command(tool_call.name, tool_call.tool_input)
+    return command is not None and SHELL_REPLY_COMMAND_PATTERN.search(command) is not None
+
+
+def _reply_comment_ids(all_tool_input_fields: dict[str, object]) -> frozenset[str]:
+    comment_id = all_tool_input_fields.get(COMMENT_ID_INPUT_KEY)
+    if isinstance(comment_id, (int, float)) and not isinstance(comment_id, bool):
+        return frozenset({str(int(comment_id))})
+    if isinstance(comment_id, str) and comment_id.isdigit():
+        return frozenset({comment_id})
+    return frozenset()
+
+
+def _reply_targets(tool_call: TranscriptToolCall) -> tuple[frozenset[str], frozenset[str]]:
+    command = _shell_command(tool_call.name, tool_call.tool_input)
+    if command is None:
+        return frozenset(), _reply_comment_ids(tool_call.tool_input)
+    return frozenset(THREAD_ID_PATTERN.findall(command)), frozenset(SHELL_REPLY_COMMENT_ID_PATTERN.findall(command))
+
+
+def _result_content_texts(result_content: object) -> list[str]:
+    if isinstance(result_content, str):
+        return [result_content]
+    all_parts = result_content if isinstance(result_content, list) else []
+    return [
+        each_part[TEXT_FIELD]
+        for each_part in all_parts
+        if isinstance(each_part, dict)
+        and each_part.get("type") == TEXT_BLOCK_TYPE
+        and isinstance(each_part.get(TEXT_FIELD), str)
+    ]
+
+
+def _successful_result_texts(all_entry_fields: dict[str, object]) -> Iterator[str]:
+    message = all_entry_fields.get("message")
+    content = message.get("content") if isinstance(message, dict) else None
+    for each_block in content if isinstance(content, list) else []:
+        if not isinstance(each_block, dict) or each_block.get("type") != TOOL_RESULT_BLOCK_TYPE:
+            continue
+        if each_block.get(IS_ERROR_FIELD) is not True:
+            yield from _result_content_texts(each_block.get("content"))
+
+
+def _thread_ids_by_comment_id_in_text(text: str) -> dict[str, str]:
+    all_thread_matches = list(THREAD_ID_PATTERN.finditer(text))
+    if not all_thread_matches:
+        return {}
+    all_span_ends = [each_match.start() for each_match in all_thread_matches[1:]] + [len(text)]
+    return {
+        each_anchor.group(1): each_thread_match.group()
+        for each_thread_match, each_span_end in zip(all_thread_matches, all_span_ends, strict=True)
+        for each_anchor in COMMENT_ANCHOR_PATTERN.finditer(text, each_thread_match.end(), each_span_end)
+    }
+
+
+def thread_ids_by_comment_id(all_transcript_lines: Iterable[str]) -> dict[str, str]:
+    """Return each review comment id mapped to its thread id, read from successful tool results.
+
+    ::
+
+        get_review_comments {"id": "PRRT_a", "comments": [{"html_url": "...#discussion_r9"}]}  -> {"9": "PRRT_a"}
+        gh api graphql {"id": "PRRT_a", "comments": {"nodes": [{"databaseId": 9}]}}           -> {"9": "PRRT_a"}
 
+    A comment id belongs to the nearest thread id before it in the same result text.
 
-def has_posted_reply_since_last_resolve(all_transcript_lines: Iterable[str]) -> bool:
-    """Return whether a reply that succeeded since the last user prompt is not yet spent on a successful resolve.
+    Args:
+        all_transcript_lines: JSON transcript entries, one per line.
+    """
+    thread_id_by_comment_id: dict[str, str] = {}
+    for each_line in all_transcript_lines:
+        try:
+            entry_fields = json.loads(each_line)
+        except ValueError:
+            continue
+        if not isinstance(entry_fields, dict):
+            continue
+        for each_text in _successful_result_texts(entry_fields):
+            thread_id_by_comment_id.update(_thread_ids_by_comment_id_in_text(each_text))
+    return thread_id_by_comment_id
+
+
+def _thread_keys(all_ids: Iterable[str], all_thread_ids_by_comment_id: dict[str, str]) -> set[str]:
+    return {all_thread_ids_by_comment_id.get(each_id, each_id) for each_id in all_ids}
+
+
+def _keys_after_call(
+    all_answered_keys: set[str], tool_call: TranscriptToolCall, all_thread_ids_by_comment_id: dict[str, str]
+) -> set[str]:
+    if not tool_call.succeeded:
+        return all_answered_keys
+    spent_thread_ids = resolved_thread_ids(tool_call.name, tool_call.tool_input)
+    if spent_thread_ids is not None:
+        return all_answered_keys - _thread_keys(spent_thread_ids, all_thread_ids_by_comment_id)
+    if not is_reply_call(tool_call):
+        return all_answered_keys
+    reply_thread_ids, reply_comment_ids = _reply_targets(tool_call)
+    return all_answered_keys | _thread_keys(reply_thread_ids | reply_comment_ids, all_thread_ids_by_comment_id)
+
+
+def _answered_thread_keys(
+    all_calls: Iterable[TranscriptToolCall], all_thread_ids_by_comment_id: dict[str, str]
+) -> set[str]:
+    answered_thread_keys: set[str] = set()
+    for each_call in all_calls:
+        answered_thread_keys = _keys_after_call(answered_thread_keys, each_call, all_thread_ids_by_comment_id)
+    return answered_thread_keys
+
+
+def has_posted_reply_on_threads(all_transcript_lines: Iterable[str], all_thread_ids: frozenset[str]) -> bool:
+    """Return whether each named thread has a reply that succeeded since the last user prompt and its last resolve.
 
     ::
 
-        prompt, reply ok, resolve pending                                 -> True
-        prompt, reply refused by a hook, resolve                          -> False
-        prompt, resolve                                                   -> False
-        prompt, reply ok, resolve ok, resolve pending                     -> False
-        prompt, reply ok, reply ok, resolve ok, resolve pending           -> True
+        prompt, read, reply ok on thread A, resolve A pending            -> True
+        prompt, read, reply ok on thread A, resolve B pending            -> False
+        prompt, reply refused by a hook, resolve A                       -> False
+        prompt, reply ok on A, resolve A ok, resolve A pending           -> False
+        prompt, reply ok on A and on B, resolve A ok, resolve B pending  -> True
+        no thread ids                                                    -> False
 
-    Each successful resolve spends one successful reply. A failed or denied
+    A successful resolve spends the replies on its threads. A failed or denied
     resolve spends none, so a retry after a resolve error needs no second reply.
+    A reply by comment id counts for the thread that a successful tool result,
+    such as ``pull_request_read`` ``get_review_comments``, lists the comment under,
+    and for a resolve that names the same comment id.
 
     Args:
         all_transcript_lines: JSON transcript entries, one per line.
+        all_thread_ids: The thread ids, or comment ids, the pending resolve names.
     """
-    unspent_reply_count = 0
-    for each_call in tool_calls_since_last_prompt(all_transcript_lines):
-        unspent_reply_count = _unspent_reply_count_after(unspent_reply_count, each_call)
-    return unspent_reply_count > 0
+    all_lines = list(all_transcript_lines)
+    thread_id_by_comment_id = thread_ids_by_comment_id(all_lines)
+    answered_thread_keys = _answered_thread_keys(tool_calls_since_last_prompt(all_lines), thread_id_by_comment_id)
+    return bool(all_thread_ids) and _thread_keys(all_thread_ids, thread_id_by_comment_id) <= answered_thread_keys
 
 
-def _unspent_reply_count_after(unspent_reply_count: int, tool_call: TranscriptToolCall) -> int:
-    if not tool_call.succeeded:
-        return unspent_reply_count
-    if is_resolve_call(tool_call.name):
-        return max(0, unspent_reply_count - 1)
-    if is_reply_call(tool_call):
-        return unspent_reply_count + 1
-    return unspent_reply_count
-
-
-def _transcript_shows_reply(transcript_path: str) -> bool | None:
+def _transcript_shows_reply(transcript_path: str, all_thread_ids: frozenset[str]) -> bool | None:
     try:
         with open(transcript_path, encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY) as transcript:
-            return has_posted_reply_since_last_resolve(transcript)
+            return has_posted_reply_on_threads(transcript, all_thread_ids)
     except OSError:
         return None
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for a review thread resolve with no posted reply before it, else None.
+    """Return a deny for a review thread resolve with no posted reply on that thread before it, else None.
 
     ::
 
-        resolve after a reply that posted        -> None
-        resolve after a reply a hook refused     -> MISSING_REPLY_REASON
-        resolve with no reply this turn          -> MISSING_REPLY_REASON
-        second resolve after one reply           -> MISSING_REPLY_REASON
-        resolve with an unreadable transcript    -> None
-        any other tool                           -> None
+        resolve after a reply on the thread that posted  -> None
+        resolve after a reply on another thread          -> MISSING_REPLY_REASON
+        resolve after a reply a hook refused             -> MISSING_REPLY_REASON
+        resolve with no reply this turn                  -> MISSING_REPLY_REASON
+        second resolve after one reply                   -> MISSING_REPLY_REASON
+        gh api graphql resolveReviewThread, no reply     -> MISSING_REPLY_REASON
+        gh api .../ccr/comments/9/resolve, no reply      -> MISSING_REPLY_REASON
+        pull_request_review_write resolve_thread, no reply -> MISSING_REPLY_REASON
+        resolve with an unreadable transcript            -> None
+        any other tool or shell command                  -> None
 
     The gate reads the calling agent's own transcript: a subagent's file when
     the payload names one, else the session transcript.
@@ -115,12 +273,16 @@ def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | N
     Args:
         all_payload_fields: The parsed PreToolUse input.
     """
-    if not is_resolve_call(all_payload_fields.get("tool_name")):
+    tool_input = all_payload_fields.get("tool_input")
+    all_thread_ids = resolved_thread_ids(
+        all_payload_fields.get("tool_name"), tool_input if isinstance(tool_input, dict) else {}
+    )
+    if all_thread_ids is None:
         return None
     all_paths = transcript_paths(all_payload_fields)
     if not all_paths:
         return None
-    shows_reply = _transcript_shows_reply(all_paths[-1])
+    shows_reply = _transcript_shows_reply(all_paths[-1], all_thread_ids)
     if shows_reply is None or shows_reply:
         return None
     return deny_decision(MISSING_REPLY_REASON)

package/hooks/blocking/session_title_turn_gate.py

@@ -1,18 +1,27 @@
 #!/usr/bin/env python3
-"""Stop hook that holds a turn until it sets the session title.
+"""Stop hook that holds a turn only when the session title shows a stale status.
+
+The title's emoji tells the user whether a session needs them. The gate leaves
+a title alone while it still fits, and holds the turn once when it does not::
+
+    no title set yet                                   -> hold
+    red flag, and this turn's prompt asks for work     -> hold: the user acted on it
+    check mark, and the task list has open items       -> hold: work is open again
+    hourglass, every item completed or deleted         -> hold: nothing runs
+    anything else                                      -> pass
+
+A turn that set a title passes, because the agent's choice stands. So does a
+turn that called no tool other than the title tool, and a held turn
+(``stop_hook_active``). The gate adds at most one step to a turn.
 
 A turn starts after the latest user prompt in the transcript. Tool results,
 meta entries, sidechain entries and compaction summaries are not prompts, and
 a Stop hook block lands as an attachment, so a held turn stays the same turn.
 A title call on a sidechain entry belongs to a subagent and does not count.
-The turn may end once a tool whose name ends in __set_session_title ran in it
-and its result came back without an error. A title the format gate denied
-does not count. A turn that called no tool other than the title tool may also
-end once an earlier main-chain turn set the title, since that title still
-shows and a text-only turn starts no new task. A held turn
-(``stop_hook_active`` true) whose title call failed may end, so a title tool
-that keeps failing cannot hold it forever. A held turn with no title call
-stays held, whichever Stop gate held it.
+A title the format gate denied does not count either.
+
+The task list comes from ``open_tasks_stop_gate.session_task_items``. Whether
+a prompt asks for work comes from ``open_task_asks.is_ask``.
 
 The session has the title tool when a transcript record names it::
 
@@ -25,8 +34,7 @@ or with an unreadable transcript, the hook lets the turn end, so Codex,
 Cursor and sessions without the tool keep working.
 
 A block writes ``{"decision": "block", "reason": ...}`` to stdout. The reason
-names the four status emoji and tells the model to close with one short
-sentence, so the held turn neither ends empty nor repeats the reply.
+names the shown title, why it does not fit, and the four status emoji.
 """
 
 from __future__ import annotations
@@ -38,10 +46,18 @@ 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)
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
 
 from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.open_tasks_stop_gate_constants import INCOMPLETE_STATUSES
+from open_task_asks import is_ask
+from open_tasks_stop_gate import session_task_items
+from open_tasks_transcript import TaskItem, replayed_transcript
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.session_title_constants import (
+    ALL_ITEMS_COMPLETED_REASON,
     ALL_SKIPPED_PROMPT_FLAGS,
     ALL_TOOL_LISTING_NAME_KEYS,
     ALL_TOOL_LISTING_RECORD_KEYS,
@@ -50,17 +66,27 @@ from hooks_constants.session_title_constants import (
     ATTACHMENT_KEY,
     BLOCK_DECISION,
     BLOCK_ID_KEY,
+    BLOCK_INPUT_KEY,
     BLOCK_NAME_KEY,
+    CHECK_MARK_STATUS,
     CONTENT_KEY,
     DECISION_KEY,
     DECODE_ERRORS_POLICY,
     ENTRY_TYPE_KEY,
+    HOURGLASS_STATUS,
     IS_ERROR_KEY,
     MESSAGE_KEY,
+    NO_TITLE_REASON,
+    OPEN_ITEMS_REASON,
     REASON_KEY,
+    RED_FLAG_STATUS,
     REMOVED_NAMES_KEY,
+    SESSION_ID_KEY,
     SIDECHAIN_FLAG_KEY,
+    STALE_FLAG_REASON,
+    STATUS_PREFIX_PATTERN,
     STOP_HOOK_ACTIVE_KEY,
+    TITLE_INPUT_KEY,
     TITLE_TOOL_DISPLAY_SEPARATOR,
     TITLE_TOOL_NAME_PATTERN,
     TOOL_RESULT_BLOCK_TYPE,
@@ -175,10 +201,6 @@ def _turn_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object
     return _main_chain(all_entries[_last_prompt_index(all_entries) + 1 :])
 
 
-def _earlier_entries(all_entries: list[dict[str, object]]) -> list[dict[str, object]]:
-    return _main_chain(all_entries[: max(_last_prompt_index(all_entries), 0)])
-
-
 def _title_call_ids(all_turn_entries: list[dict[str, object]]) -> set[object]:
     return {
         each_block.get(BLOCK_ID_KEY)
@@ -188,18 +210,6 @@ def _title_call_ids(all_turn_entries: list[dict[str, object]]) -> set[object]:
     }
 
 
-def title_attempted_this_turn(all_entries: list[dict[str, object]]) -> bool:
-    """Return True when a title call ran after the latest prompt, whatever its result.
-
-    Args:
-        all_entries: The transcript entries, oldest first.
-
-    Returns:
-        True when this turn called the title tool.
-    """
-    return bool(_title_call_ids(_turn_entries(all_entries)))
-
-
 def title_set_this_turn(all_entries: list[dict[str, object]]) -> bool:
     """Return True when a title call after the latest prompt came back without an error.
 
@@ -218,18 +228,6 @@ def title_set_this_turn(all_entries: list[dict[str, object]]) -> bool:
     return _title_succeeded_in(_turn_entries(all_entries))
 
 
-def title_set_before_this_turn(all_entries: list[dict[str, object]]) -> bool:
-    """Return True when a main-chain title call before the latest prompt came back without an error.
-
-    Args:
-        all_entries: The transcript entries, oldest first.
-
-    Returns:
-        True when an earlier turn set the title the session still shows.
-    """
-    return _title_succeeded_in(_earlier_entries(all_entries))
-
-
 def turn_ran_a_tool(all_entries: list[dict[str, object]]) -> bool:
     """Return True when this turn called any tool other than the title tool.
 
@@ -246,46 +244,130 @@ def turn_ran_a_tool(all_entries: list[dict[str, object]]) -> bool:
     )
 
 
-def _title_succeeded_in(all_scoped_entries: list[dict[str, object]]) -> bool:
+def _successful_title_call_ids(all_scoped_entries: list[dict[str, object]]) -> set[object]:
     all_title_call_ids = _title_call_ids(all_scoped_entries)
-    return any(
-        each_block.get(ENTRY_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE
-        and each_block.get(TOOL_USE_ID_KEY) in all_title_call_ids
-        and not each_block.get(IS_ERROR_KEY)
+    return {
+        each_block.get(TOOL_USE_ID_KEY)
         for each_entry in all_scoped_entries
         if each_entry.get(ENTRY_TYPE_KEY) == USER_ENTRY_TYPE
         for each_block in _content_blocks(each_entry)
-    )
+        if each_block.get(ENTRY_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE
+        and each_block.get(TOOL_USE_ID_KEY) in all_title_call_ids
+        and not each_block.get(IS_ERROR_KEY)
+    }
+
+
+def _title_succeeded_in(all_scoped_entries: list[dict[str, object]]) -> bool:
+    return bool(_successful_title_call_ids(all_scoped_entries))
+
+
+def _title_input(all_block_fields: dict[str, object]) -> str | None:
+    all_input_fields = all_block_fields.get(BLOCK_INPUT_KEY)
+    title = all_input_fields.get(TITLE_INPUT_KEY) if isinstance(all_input_fields, dict) else None
+    return title if isinstance(title, str) else None
+
+
+def shown_title(all_entries: list[dict[str, object]]) -> str | None:
+    """Return the title of the last main-chain title call that came back without an error.
+
+    ::
+
+        "\u23f3 Export" ok, then "\u2705 Export" denied   -> "\u23f3 Export"
+        no title call                                -> None
+
+    Args:
+        all_entries: The transcript entries, oldest first.
+
+    Returns:
+        The title the session shows, or None when no title call succeeded.
+    """
+    all_main_entries = _main_chain(all_entries)
+    all_successful_ids = _successful_title_call_ids(all_main_entries)
+    all_titles = [
+        _title_input(each_block)
+        for each_entry in all_main_entries
+        for each_block in _tool_use_blocks(each_entry)
+        if each_block.get(BLOCK_ID_KEY) in all_successful_ids
+    ]
+    all_text_titles = [each_title for each_title in all_titles if each_title is not None]
+    return all_text_titles[-1] if all_text_titles else None
+
+
+def title_status(title: str) -> str | None:
+    """Return the status emoji the title starts with, without a variation selector, or None."""
+    status_match = STATUS_PREFIX_PATTERN.match(title)
+    return status_match.group(1) if status_match else None
+
+
+def stale_status_reason(title: str, is_ask_turn: bool, all_task_items: list[TaskItem]) -> str | None:
+    """Return why the shown title does not fit the session's state, or None when it fits.
+
+    ::
+
+        red flag, the prompt asks for work          -> reason
+        check mark, an item is pending              -> reason
+        hourglass, every item completed or deleted  -> reason
+        hourglass, an item is in progress           -> None
+
+    Args:
+        title: The title the session shows.
+        is_ask_turn: True when the prompt that started this turn asks for work.
+        all_task_items: The session's task list.
+
+    Returns:
+        The reason the status is stale, with the title filled in, or None.
+    """
+    status = title_status(title)
+    has_open_items = any(each_item.status in INCOMPLETE_STATUSES for each_item in all_task_items)
+    is_all_completed = bool(all_task_items) and not has_open_items
+    if status == RED_FLAG_STATUS and is_ask_turn:
+        return STALE_FLAG_REASON.format(title=title)
+    if status == CHECK_MARK_STATUS and has_open_items:
+        return OPEN_ITEMS_REASON.format(title=title)
+    if status == HOURGLASS_STATUS and is_all_completed:
+        return ALL_ITEMS_COMPLETED_REASON.format(title=title)
+    return None
 
 
 def turn_block_reason(
-    all_entries: list[dict[str, object]], is_stop_hook_active: bool
+    all_entries: list[dict[str, object]],
+    is_stop_hook_active: bool,
+    is_ask_turn: bool,
+    all_task_items: list[TaskItem],
 ) -> str | None:
     """Return the reason to hold the turn, or None when the turn may end.
 
     ::
 
-        no title tool in the transcript                         -> None
-        title set this turn                                     -> None
-        only title calls this turn, earlier turn set the title  -> None
-        held turn whose title call failed (stop_hook_active)    -> None
-        no title call this turn                                 -> reason
+        no title tool in the transcript                  -> None
+        held turn (stop_hook_active)                     -> None
+        title set this turn                              -> None
+        no tool other than the title tool this turn      -> None
+        no title set in the session yet                  -> reason
+        shown title has a stale status                   -> reason
+        shown title still fits                           -> None
 
     Args:
         all_entries: The transcript entries, oldest first.
         is_stop_hook_active: True when a Stop hook already held this turn.
+        is_ask_turn: True when the prompt that started this turn asks for work.
+        all_task_items: The session's task list.
 
     Returns:
         The block reason that names the title tool, or None.
     """
     all_title_tools = available_title_tools(all_entries)
-    if not all_title_tools or title_set_this_turn(all_entries):
+    if not all_title_tools or is_stop_hook_active or title_set_this_turn(all_entries):
         return None
-    if title_set_before_this_turn(all_entries) and not turn_ran_a_tool(all_entries):
+    if not turn_ran_a_tool(all_entries):
         return None
-    if is_stop_hook_active and title_attempted_this_turn(all_entries):
+    title = shown_title(all_entries)
+    stale_reason = NO_TITLE_REASON if title is None else stale_status_reason(title, is_ask_turn, all_task_items)
+    if stale_reason is None:
         return None
-    return TURN_BLOCK_REASON.format(tool_name=TITLE_TOOL_DISPLAY_SEPARATOR.join(all_title_tools))
+    return TURN_BLOCK_REASON.format(
+        why=stale_reason, tool_name=TITLE_TOOL_DISPLAY_SEPARATOR.join(all_title_tools)
+    )
 
 
 def _parsed_entry(line: str) -> dict[str, object] | None:
@@ -316,9 +398,13 @@ def main() -> int:
     hook_input = read_hook_input_dictionary_from_stdin()
     if hook_input is None:
         return ALLOW_EXIT_CODE
+    transcript_path = hook_input.get(TRANSCRIPT_PATH_KEY)
+    replay = replayed_transcript(transcript_path)
     block_reason = turn_block_reason(
-        read_transcript_entries(hook_input.get(TRANSCRIPT_PATH_KEY)),
+        read_transcript_entries(transcript_path),
         hook_input.get(STOP_HOOK_ACTIVE_KEY) is True,
+        is_ask(replay.turn_prompt_text),
+        session_task_items(hook_input.get(SESSION_ID_KEY), replay),
     )
     if block_reason is None:
         return ALLOW_EXIT_CODE