claude-dev-env 8.98.9 → 8.98.11

package/hooks/blocking/open_tasks_transcript.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Rebuild a session task list and its last assistant text from a transcript.
+"""Rebuild a session task list and what its current turn did from a transcript.
 
 The open tasks Stop gate reads four transcript shapes, replayed in order::
 
@@ -17,15 +17,19 @@ 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::
+The replay also notes what the current turn did::
 
-    AskUserQuestion, mcp__hearthbot__ask_decision, mcp__hearthbot__request_decision   (Claude Code)
-    request_user_input, request_user_input_async                                       (Codex)
+    turn_prompt_text         the text of the prompt that started the turn
+    has_turn_tracker_write   a TaskCreate, TaskUpdate, TodoWrite, update_plan, or desktop plan call ran
+    has_turn_work_tool       any other assistant tool call ran, except the title tool,
+                             AskUserQuestion, a hearthbot decision card, ToolSearch,
+                             TaskList, TaskGet, and the Codex request_user_input card
 
 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.
+A Codex ``response_item`` user message starts a Codex turn.
 
 The Cursor CLI can also reach TodoWrite through ``CallDynamicTool``, with the
 TodoWrite input under ``arguments``; that call counts as the TodoWrite call.
@@ -36,7 +40,6 @@ from __future__ import annotations
 import json
 import re
 import sys
-from datetime import datetime
 from pathlib import Path
 from typing import NamedTuple
 
@@ -47,6 +50,9 @@ if hooks_root_directory not in sys.path:
 from hooks_constants.open_tasks_stop_gate_constants import (
     ALL_SKIPPED_PROMPT_FLAGS,
     ASSISTANT_RECORD_TYPE,
+    ALL_CODEX_TOOL_CALL_TYPES,
+    ALL_NON_WORK_TOOL_NAMES,
+    ALL_TRACKER_TOOL_NAMES,
     ASSISTANT_ROLE,
     CCD_PLAN_ADVANCE_KEY,
     CCD_PLAN_CONTENT_KEY,
@@ -56,19 +62,16 @@ 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,
@@ -77,9 +80,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     IN_PROGRESS_STATUS,
     MESSAGE_KEY,
     PENDING_STATUS,
-    RECORD_TIMESTAMP_KEY,
     RECORD_TYPE_KEY,
-    REPLY_TEXT_SEPARATOR,
     ROLE_KEY,
     STOP_HOOK_FEEDBACK_PREFIX,
     TASK_CREATED_PATTERN,
@@ -88,6 +89,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     TASK_STATUS_KEY,
     TASK_SUBJECT_KEY,
     TASK_UPDATE_ID_KEY,
+    SESSION_TITLE_TOOL_SUFFIX,
     TASK_UPDATE_TOOL_NAME,
     TEXT_KEY,
     TODOS_KEY,
@@ -100,8 +102,6 @@ from hooks_constants.open_tasks_stop_gate_constants import (
     TOOL_RESULT_BLOCK_TYPE,
     TOOL_USE_BLOCK_TYPE,
     TOOL_USE_ID_KEY,
-    UTC_OFFSET_TEXT,
-    UTC_SUFFIX,
     USER_RECORD_TYPE,
     USER_ROLE,
     UTF8_ENCODING,
@@ -116,15 +116,11 @@ class TaskItem(NamedTuple):
         item_id: The task number or position, as text.
         subject: The item's wording.
         status: The item's status, such as ``pending`` or ``completed``.
-        listed_at: For a desktop plan item, seconds since the epoch of the last list that held it.
-        is_carried: True for a desktop plan item a replacing list left out.
     """
 
     item_id: str
     subject: str
     status: str
-    listed_at: float | None = None
-    is_carried: bool = False
 
 
 def normalized_text(text: str) -> str:
@@ -132,17 +128,6 @@ def normalized_text(text: str) -> str:
     return WORD_SEPARATOR.join(text.lower().split())
 
 
-def record_epoch(all_record_fields: dict[str, object]) -> float | None:
-    """Return the record's ISO ``timestamp`` as seconds since the epoch, or None."""
-    timestamp_value = all_record_fields.get(RECORD_TIMESTAMP_KEY)
-    if not isinstance(timestamp_value, str):
-        return None
-    try:
-        return datetime.fromisoformat(timestamp_value.replace(UTC_SUFFIX, UTC_OFFSET_TEXT)).timestamp()
-    except ValueError:
-        return None
-
-
 def parsed_object(json_text: str) -> dict[str, object] | None:
     """Return the JSON object in the text, or None for anything else."""
     try:
@@ -182,45 +167,76 @@ 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 _text_of_blocks(all_blocks: list[dict[str, object]]) -> str:
+    return WORD_SEPARATOR.join(
+        str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if isinstance(each_block.get(TEXT_KEY), str)
+    )
 
 
-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."""
+def claude_prompt_text(all_record_fields: dict[str, object]) -> str | None:
+    """Return the prompt text of a record that starts a turn, or None for any other record."""
     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
+        return None
     if any(all_record_fields.get(each_flag) for each_flag in ALL_SKIPPED_PROMPT_FLAGS):
-        return False
+        return None
     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
+            return None
         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)
+            return _text_of_blocks(all_blocks)
+        prompt_text = _text_of_blocks(all_blocks)
+    if not prompt_text.strip() or prompt_text.lstrip().startswith(STOP_HOOK_FEEDBACK_PREFIX):
+        return None
+    return prompt_text
 
 
-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."""
+def _codex_payload(all_record_fields: dict[str, object]) -> dict[str, object] | 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
+    return payload_body
+
+
+def codex_prompt_text(all_record_fields: dict[str, object]) -> str | None:
+    """Return the text of a Codex user message record, or None for any other record."""
+    payload_body = _codex_payload(all_record_fields)
+    if payload_body is None or payload_body.get(RECORD_TYPE_KEY) != CODEX_MESSAGE_TYPE or payload_body.get(ROLE_KEY) != USER_ROLE:
+        return None
+    content_value = payload_body.get(CONTENT_KEY)
+    if isinstance(content_value, str):
+        return content_value
+    all_blocks = [each_block for each_block in content_value if isinstance(each_block, dict)] if isinstance(content_value, list) else []
+    return _text_of_blocks(all_blocks)
+
+
+def is_codex_work_call(all_record_fields: dict[str, object]) -> bool:
+    """Return True for a Codex tool call record other than ``update_plan`` or a question card call."""
+    payload_body = _codex_payload(all_record_fields)
+    if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
+        return False
+    tool_name = payload_body.get(TOOL_NAME_KEY)
+    return tool_name != CODEX_PLAN_TOOL_NAME and is_work_tool_name(tool_name)
+
+
+def is_work_tool_name(tool_name: object) -> bool:
+    """Return True for a tool name other than a non-work tool or the session title tool."""
+    return not (
+        isinstance(tool_name, str)
+        and (tool_name in ALL_NON_WORK_TOOL_NAMES or tool_name.endswith(SESSION_TITLE_TOOL_SUFFIX))
+    )
+
+
+def is_assistant_record(all_record_fields: dict[str, object]) -> bool:
+    """Return True for a record the assistant wrote, by its type, its role, or its message role."""
+    message_body = all_record_fields.get(MESSAGE_KEY)
+    message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
+    return ASSISTANT_ROLE in (all_record_fields.get(ROLE_KEY), all_record_fields.get(RECORD_TYPE_KEY), message_role)
 
 
 def _numbered_items(all_entries: object, subject_key: str) -> list[TaskItem]:
@@ -305,7 +321,7 @@ def unwrapped_tool_call(tool_name: str, all_input_fields: dict[str, object]) ->
 
 
 class TranscriptReplay:
-    """Fold transcript records into the newest task list they describe."""
+    """Fold transcript records into the newest task list they describe and what the current turn did."""
 
     def __init__(self) -> None:
         self.latest_items: list[TaskItem] | None = None
@@ -313,37 +329,44 @@ class TranscriptReplay:
         self.subject_by_tool_use_id: dict[str, str] = {}
         self.plan_items: list[TaskItem] | None = None
         self.own_plan_count = 0
-        self.last_assistant_text = ""
-        self.all_assistant_texts: list[str] = []
-        self.has_turn_decision_card = False
+        self.turn_prompt_text = ""
+        self.has_turn_tracker_write = False
+        self.has_turn_work_tool = False
+
+    def start_turn(self, prompt_text: str) -> None:
+        self.turn_prompt_text = prompt_text
+        self.has_turn_tracker_write = False
+        self.has_turn_work_tool = 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
+        prompt_text = codex_prompt_text(all_record_fields)
+        if prompt_text is None:
+            prompt_text = claude_prompt_text(all_record_fields)
+        if prompt_text is not None:
+            self.start_turn(prompt_text)
             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
+            self.has_turn_tracker_write = True
             return
-        all_blocks = _content_blocks(all_record_fields)
-        is_assistant_record = all_record_fields.get(RECORD_TYPE_KEY) == ASSISTANT_RECORD_TYPE
-        for each_block in all_blocks:
+        if is_codex_work_call(all_record_fields):
+            self.has_turn_work_tool = True
+            return
+        is_typed_assistant_record = all_record_fields.get(RECORD_TYPE_KEY) == ASSISTANT_RECORD_TYPE
+        is_from_assistant = is_assistant_record(all_record_fields)
+        for each_block in _content_blocks(all_record_fields):
             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))
+            if is_typed_assistant_record and each_block.get(TOOL_NAME_KEY) == CCD_PLAN_TOOL_NAME and isinstance(plan_input, dict):
+                self.apply_desktop_plan(plan_input)
+                self.has_turn_tracker_write = True
             else:
-                self.apply_block(each_block)
-        self.note_assistant_text(all_record_fields, all_blocks)
+                self.apply_block(each_block, is_from_assistant)
 
-    def apply_desktop_plan(self, all_plan_fields: dict[str, object], listed_at: float | None) -> None:
+    def apply_desktop_plan(self, all_plan_fields: dict[str, object]) -> None:
         all_listed_entries = all_plan_fields.get(CCD_PLAN_ITEMS_KEY)
         if isinstance(all_listed_entries, list):
-            self.replace_desktop_plan(all_listed_entries, listed_at)
+            self.replace_desktop_plan(all_listed_entries)
             return
         all_own_items = (self.plan_items or [])[: self.own_plan_count]
         all_done_positions = all_plan_fields.get(CCD_PLAN_DONE_KEY)
@@ -357,41 +380,37 @@ class TranscriptReplay:
             all_own_items = advanced_items(all_own_items)
         self.plan_items = all_own_items + (self.plan_items or [])[self.own_plan_count :]
 
-    def replace_desktop_plan(self, all_listed_entries: list[object], listed_at: float | None) -> None:
+    def replace_desktop_plan(self, all_listed_entries: list[object]) -> None:
         all_own_items = [
-            each_item._replace(item_id=CCD_PLAN_ITEM_ID_TEMPLATE.format(position=each_item.item_id), listed_at=listed_at)
+            each_item._replace(item_id=CCD_PLAN_ITEM_ID_TEMPLATE.format(position=each_item.item_id))
             for each_item in _numbered_items(all_listed_entries, CCD_PLAN_CONTENT_KEY)
         ]
         all_listed_subjects = {normalized_text(each_item.subject) for each_item in all_own_items}
         all_carried_items = [
-            each_item._replace(is_carried=True)
+            each_item
             for each_item in self.plan_items or []
             if each_item.status in INCOMPLETE_STATUSES and normalized_text(each_item.subject) not in all_listed_subjects
         ]
         self.plan_items = all_own_items + all_carried_items
         self.own_plan_count = len(all_own_items)
 
-    def note_assistant_text(self, all_record_fields: dict[str, object], all_blocks: list[dict[str, object]]) -> None:
-        message_body = all_record_fields.get(MESSAGE_KEY)
-        message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
-        if ASSISTANT_ROLE not in (all_record_fields.get(ROLE_KEY), all_record_fields.get(RECORD_TYPE_KEY), message_role):
-            return
-        record_text = REPLY_TEXT_SEPARATOR.join(
-            str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if each_block.get(RECORD_TYPE_KEY) == TEXT_KEY
-        ).strip()
-        if record_text:
-            self.last_assistant_text = record_text
-            self.all_assistant_texts.append(record_text)
-
-    def apply_block(self, all_block_fields: dict[str, object]) -> None:
+    def apply_block(self, all_block_fields: dict[str, object], is_from_assistant: bool) -> None:
         block_type = all_block_fields.get(RECORD_TYPE_KEY)
         tool_input = all_block_fields.get(TOOL_INPUT_KEY)
         if block_type == TOOL_USE_BLOCK_TYPE and isinstance(tool_input, dict):
             tool_name, all_tool_arguments = unwrapped_tool_call(str(all_block_fields.get(TOOL_NAME_KEY)), tool_input)
             self.apply_tool_use(tool_name, str(all_block_fields.get(TASK_ID_KEY)), all_tool_arguments)
+            if is_from_assistant:
+                self.note_turn_tool(tool_name)
         elif block_type == TOOL_RESULT_BLOCK_TYPE:
             self.apply_tool_result(all_block_fields)
 
+    def note_turn_tool(self, tool_name: str) -> None:
+        if tool_name in ALL_TRACKER_TOOL_NAMES:
+            self.has_turn_tracker_write = True
+        elif is_work_tool_name(tool_name):
+            self.has_turn_work_tool = True
+
     def apply_tool_use(self, tool_name: str, tool_use_id: str, all_input_fields: dict[str, object]) -> None:
         if tool_name == TODO_WRITE_TOOL_NAME:
             all_todo_entries = all_input_fields.get(TODOS_KEY)
@@ -433,13 +452,8 @@ class TranscriptReplay:
 
 
 def replayed_transcript(transcript_path: object) -> TranscriptReplay:
-    """Fold every transcript record into one replay of the task list and the last assistant text."""
+    """Fold every transcript record into one replay of the task list and the current turn."""
     replay = TranscriptReplay()
     for each_record in _transcript_records(transcript_path):
         replay.apply_record(each_record)
     return replay
-
-
-def transcript_items(transcript_path: object) -> list[TaskItem] | None:
-    """Rebuild the task list from TaskCreate/TaskUpdate, TodoWrite, and Codex update_plan calls."""
-    return replayed_transcript(transcript_path).items()

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