claude-dev-env 8.98.9 → 8.98.10

package/hooks/features/conduct-gates.md

@@ -6,14 +6,14 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on.
 - `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with. Its `windows_path_violation` blocks a path the terminal would render without one of its backslashes.
-- `blocking/open_tasks_stop_gate.py` holds the end of a turn while the session has open items that the closing reply does not name on a `Blocked:` or `Open:` line. It merges the task store, the transcript task calls, the desktop `mcp__ccd_turn__update_plan` plan, and the recorded asks. A transcript item whose subject the task store holds is dropped, and every other item stays. `blocking/open_tasks_transcript.py` rebuilds the task list and the last reply from the transcript for it. Each new desktop plan list carries the unfinished items of the list before it after its own items, so `done` and `start` positions still point at its own items. An ask stays open until a reply line `Done: #ask-N` closes it. A line `Dropped: <#ask-N or carried item> - "<quote>"` closes an ask or a carried plan item when the quote is in a prompt the user sent after that ask or that list.
-- `session/open_task_ask_recorder.py` records each prompt in `~/.claude/open-task-asks/<session id>.json`, outside the task store. A prompt that asks for work gets the next `#ask-N` id. A question-only prompt, an acknowledgement such as `thanks!`, an empty prompt, a prompt of only `<system-reminder>` blocks, and an envelope such as `<agent-message>` or `<task-notification>` get none.
+- `blocking/open_tasks_stop_gate.py` holds the end of a turn once when the prompt that started it asks for work, the turn ran a work tool, and the turn made no tracker call: TaskCreate, TaskUpdate, TodoWrite, the Codex `update_plan`, or the desktop `mcp__ccd_turn__update_plan`. A work tool is any tool but a tracker call, the session title tool, `AskUserQuestion`, a hearthbot decision card, Codex `request_user_input`, `ToolSearch`, `TaskList`, or `TaskGet`. It never reads the reply text. `open_task_asks.is_ask` decides whether a prompt asks for work: a question-only prompt, an acknowledgement such as `thanks!`, an empty prompt, a prompt of only `<system-reminder>` blocks, and an envelope such as `<agent-message>` or `<task-notification>` do not. `blocking/open_tasks_transcript.py` replays the transcript for it: the turn's prompt, its tool calls, and the task list. `session_task_items` merges the task store with the transcript items whose subject the store does not hold, for the session title gate.
+- `session/tracking_nudge.py` adds one `additionalContext` note to a prompt that asks for work. The note asks for a task list item. When the title shows the red flag or the check mark, it also asks for the hourglass before other work. It never blocks.
 - The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies the first claim about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
 - `blocking/chat_reply_gate.py` runs the `reply_length_gate.py` reply checks on a plain chat reply, which is no tool call. On `UserPromptSubmit` it adds the reply rules as `additionalContext`. On `MessageDisplay` it holds each streamed batch until the message ends. A message that passes shows whole. A message that fails shows as a draft from `claude -p` on Haiku that passes the same checks, and the original shows when two drafts fail. The draft changes only the text on screen, so the next `UserPromptSubmit` tells the agent the text the user saw, and `SessionEnd` deletes the stored draft. The [reply arena harness](https://github.com/jl-cmd-projects/claude-dev-env/tree/160349b90f627ea542fc6bc7b2b7f86dcbf98b73/tests/reply_arena) ran the comparison that chose this display path.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
 - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
-- `blocking/session_title_turn_gate.py` holds the end of a turn in a session that has a `__set_session_title` tool until a title call in that turn comes back without an error. A turn that called no tool other than the title tool may end when an earlier turn already set the title. A held turn whose title call failed may end.
+- `blocking/session_title_turn_gate.py` holds the end of a turn once, in a session that has a `__set_session_title` tool, when the shown title does not fit the session's state: no title yet, a red flag after a prompt that asks for work, a check mark while the task list has open items, or an hourglass once every item is completed or deleted. A turn that set a title passes. A turn that called no tool other than the title tool passes, and so does a held turn.
 - `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.
@@ -29,8 +29,8 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision|AskUserQuestion|mcp__hearthbot__post_widget`, timeout `10` seconds in `hooks.json`.
 - `blocking/final_reply_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
-- `blocking/open_tasks_stop_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`. The installer also registers it on Codex `Stop` and as a native Cursor `stop` entry in `~/.cursor/hooks.json`, where a block also returns `followup_message`. A Cursor stop with status `aborted` or `error` passes. A Cursor stop whose `loop_count` is 5 or more passes, because a copy Cursor imports from `~/.claude/settings.json` has no follow-up limit.
-- `session/open_task_ask_recorder.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`. It prints nothing.
+- `blocking/open_tasks_stop_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`. The installer also registers it on Codex `Stop` and as a native Cursor `stop` entry in `~/.cursor/hooks.json`, where a block also returns `followup_message`. A Cursor stop with status `aborted` or `error` passes. A Cursor stop whose `loop_count` is above 0 passes, because a copy Cursor imports from `~/.claude/settings.json` has no follow-up limit.
+- `session/tracking_nudge.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`.
 - The claim judge runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision`, timeout `30` seconds in `hooks.json`.
 - `blocking/chat_reply_gate.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds, on `MessageDisplay`, timeout `100` seconds, and on `SessionEnd`, timeout `3` seconds, in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
@@ -57,14 +57,14 @@ Preconditions:
 - **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, or with a reply on another thread, then a resolve call, a `pull_request_review_write` `resolve_thread` call, a graphql `resolveReviewThread` command, or a `ccr/comments/<id>/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.
+- **Open tasks.** Input is a transcript whose last prompt asks for work and whose turn ran a Bash call and no tracker call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_open_tasks_stop_gate.py -q`. The adjacent test observes one `block` decision; the same turn with a TaskCreate, TaskUpdate, TodoWrite, or desktop plan call passes. A question, an acknowledgement, a `<task-notification>` envelope, a tool-free turn, and a held stop pass. The same file covers Codex and Cursor payloads.
+- **Ask nudge.** Input is a `UserPromptSubmit` payload with a work prompt, a question, and a `<task-notification>` envelope, after a transcript whose title shows the red flag. Run `python -m pytest packages/claude-dev-env/hooks/session/test_tracking_nudge.py -q`. The adjacent test observes a task list note and a title note for the work prompt, and empty stdout for the other two.
 - **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Fact with no source: ...`. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
 - **Chat reply.** Input is a `MessageDisplay` event whose message holds four sentences, the same message split over two batches, and a `UserPromptSubmit` event. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_chat_reply_gate.py -q`. The adjacent test observes the drafter's text in `displayContent`, an empty first batch, no output for three sentences, the original after two failed drafts, the shown draft in the next `additionalContext`, and the stored draft deleted at session end.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
-- **Title this turn.** Input is a transcript that lists the title tool and a turn with no title call. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_turn_gate.py -q`. The adjacent test observes a `block` decision that names the tool and the four status emoji; a turn whose title call came back without an error passes.
+- **Stale title.** Input is a transcript that lists the title tool, an earlier turn that set the red flag, and a work prompt whose turn ran a tool and set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_turn_gate.py -q`. The adjacent test observes a `block` decision that names the shown title, the tool, and the four status emoji. A carried hourglass with an item in progress passes, and so does a turn whose title call came back without an error.
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.
@@ -77,7 +77,7 @@ Preconditions:
 
 ## Gotchas
 
-- The open tasks gate reads `Done:` and `Dropped:` lines in every assistant text of the transcript, so a close holds for later stops. The ask recorder runs only from `hooks.json`, so Codex and Cursor sessions get no asks.
+- The ask nudge runs only from `hooks.json`, so Codex and Cursor sessions get no turn-start note. Their Stop gate still holds a work turn with no tracker call.
 - `blocking/step_note_gate.py` is off by default and polls for the transcript record. Subagent calls and unreadable records pass.
 - `blocking/verify_before_acting.py` runs after the tool. A block asks the agent to check the claim and undo a contradicted change.
 - The reply gate counts each nonempty list line as a sentence. Link targets and code spans add no words. Its banned words come from `reply-banned-words.json` in the Claude home, or the file `CLAUDE_REPLY_BANNED_WORDS_PATH` names, with built-in defaults.

package/hooks/hooks.json

@@ -336,7 +336,7 @@
           },
           {
             "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/open_task_ask_recorder.py",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/tracking_nudge.py",
             "timeout": 10
           },
           {

package/hooks/hooks_constants/open_tasks_stop_gate_constants.py

@@ -1,13 +1,12 @@
 """Constants for the open tasks Stop gate."""
 
 HOOK_EVENT_NAME = "Stop"
-SESSION_ID_KEY = "session_id"
 TRANSCRIPT_PATH_KEY = "transcript_path"
-LAST_ASSISTANT_MESSAGE_KEY = "last_assistant_message"
 DECISION_KEY = "decision"
 BLOCK_DECISION = "block"
 REASON_KEY = "reason"
 ALLOW_EXIT_CODE = 0
+STOP_HOOK_ACTIVE_KEY = "stop_hook_active"
 UTF8_ENCODING = "utf-8"
 WORD_SEPARATOR = " "
 TASK_LIST_ID_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_TASK_LIST_ID"
@@ -38,8 +37,6 @@ CURSOR_FOLLOWUP_MESSAGE_KEY = "followup_message"
 CURSOR_STATUS_KEY = "status"
 CURSOR_COMPLETED_STATUS = "completed"
 CURSOR_LOOP_COUNT_KEY = "loop_count"
-CURSOR_FOLLOWUP_LIMIT = 5
-REPLY_TEXT_SEPARATOR = "\n"
 TASK_UPDATE_ID_KEY = "taskId"
 TODO_WRITE_TOOL_NAME = "TodoWrite"
 DYNAMIC_TOOL_CALL_NAME = "CallDynamicTool"
@@ -59,51 +56,15 @@ CODEX_STEP_KEY = "step"
 FIRST_ITEM_NUMBER = 1
 TASK_CREATED_PATTERN = r"Task #(\d+) created"
 CREATED_TASK_ID_GROUP_INDEX = 1
-REPORT_LINE_PATTERN = r"^\s*(?:[-*]\s*)?(open|blocked)\b\s*[:\-]?\s*(.*)$"
-REPORTED_TEXT_GROUP_INDEX = 2
-WORD_BOUNDARY_PATTERN = r"\b"
 TASK_NUMBER_REFERENCE_TEMPLATE = "#{task_id}"
-ITEM_LINE_TEMPLATE = "\n- {subject}"
-BLOCK_REASON_PREFIX = "The task list still has incomplete items that this reply does not report:"
-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"
-    " called off with 'Dropped: <#ask-N or item> - \"<the user's words that called it off>\"'."
-)
 COMPLETED_STATUS = "completed"
 IN_PROGRESS_STATUS = "in_progress"
 ASSISTANT_RECORD_TYPE = "assistant"
-RECORD_TIMESTAMP_KEY = "timestamp"
-UTC_SUFFIX = "Z"
-UTC_OFFSET_TEXT = "+00:00"
 CCD_PLAN_TOOL_NAME = "mcp__ccd_turn__update_plan"
 CCD_PLAN_ITEMS_KEY = "items"
 CCD_PLAN_CONTENT_KEY = "content"
@@ -111,21 +72,7 @@ CCD_PLAN_DONE_KEY = "done"
 CCD_PLAN_START_KEY = "start"
 CCD_PLAN_ADVANCE_KEY = "advance"
 CCD_PLAN_ITEM_ID_TEMPLATE = "plan-{position}"
-ASK_ID_PREFIX = "ask-"
-ASK_ID_TEMPLATE = "ask-{ask_number}"
-ASK_LINE_TEMPLATE = "\n- #{ask_id}: {subject}"
-ASK_SUBJECT_CHARACTER_LIMIT = 120
-ASK_SUBJECT_ELLIPSIS = "..."
-ASKS_DIRECTORY_NAME = "open-task-asks"
-ASKS_FILE_SUFFIX = ".json"
-ASKS_TEMPORARY_PREFIX = ".open-task-asks-"
-ASKS_TEMPORARY_SUFFIX = ".tmp"
-ASKS_PROMPTS_KEY = "prompts"
-ASK_PROMPT_TEXT_KEY = "text"
-ASK_PROMPT_RECORDED_AT_KEY = "recorded_at"
-ASK_PROMPT_ID_KEY = "ask_id"
 PROMPT_KEY = "prompt"
-SAFE_SESSION_ID_PATTERN = r"[\w-]+"
 SENTENCE_SPLIT_PATTERN = r"(?<=[.!?])\s+|\n+"
 QUESTION_END_PATTERN = r"\?\s*$"
 YES_OR_NO_END_PATTERN = r"\byes\s+or\s+no\W*$"
@@ -140,9 +87,29 @@ ACKNOWLEDGEMENT_PATTERN = (
     r"|sounds\s+good|looks\s+good|lgtm)(?:[\s,]+(?:thanks?|thank\s+you))?\W*$"
 )
 POLITE_REQUEST_START_PATTERN = r"^\s*(?:please\b|(?:can|could|would|will)\s+you\b)"
-DONE_LINE_PATTERN = r"^\s*(?:[-*]\s*)?done\b\s*[:\-]?\s*(.*)$"
-DONE_TEXT_GROUP_INDEX = 1
-ASK_REFERENCE_PATTERN = r"#(ask-\d+)\b"
-DROPPED_LINE_PATTERN = r"^\s*(?:[-*]\s*)?dropped\b\s*[:\-]?\s*(.+?)\s+-\s+[\"“](.+?)[\"”]\s*$"
-DROPPED_TARGET_GROUP_INDEX = 1
-DROPPED_QUOTE_GROUP_INDEX = 2
+ALL_TRACKER_TOOL_NAMES = frozenset({TODO_WRITE_TOOL_NAME, TASK_CREATE_TOOL_NAME, TASK_UPDATE_TOOL_NAME})
+ALL_NON_WORK_TOOL_NAMES = frozenset(
+    {
+        "AskUserQuestion",
+        "mcp__hearthbot__ask_decision",
+        "mcp__hearthbot__request_decision",
+        "ToolSearch",
+        "TaskList",
+        "TaskGet",
+        "request_user_input",
+        "request_user_input_async",
+    }
+)
+SESSION_TITLE_TOOL_SUFFIX = "__set_session_title"
+ALL_CODEX_TOOL_CALL_TYPES = frozenset({CODEX_FUNCTION_CALL_TYPE, "custom_tool_call", "local_shell_call"})
+BLOCK_REASON = (
+    "This turn worked on the user's ask and left the task list unchanged. The user follows your work"
+    " there. Update it now: TaskCreate the ask if it has no item, and TaskUpdate each item to its"
+    " current status (TodoWrite or update_plan where that is the tracker). Then end the turn. Leave"
+    " the reply as it stands."
+)
+PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
+TASK_LIST_NUDGE = (
+    "The user follows your work in the task list. Give this ask a task list item (TaskCreate) and"
+    " keep each item's status current as the work moves."
+)

package/hooks/hooks_constants/session_title_constants.py

@@ -60,8 +60,21 @@ ALL_TOOL_LISTING_RECORD_KEYS = ("tools", "entries")
 REMOVED_NAMES_KEY = "removedNames"
 TITLE_TOOL_DISPLAY_SEPARATOR = " or "
 
+SESSION_ID_KEY = "session_id"
+BLOCK_INPUT_KEY = "input"
+RED_FLAG_STATUS = "\U0001f6a9"
+CHECK_MARK_STATUS = "\u2705"
+HOURGLASS_STATUS = "\u23f3"
+NO_TITLE_REASON = "This session has no title yet."
+STALE_FLAG_REASON = (
+    "The title '{title}' still shows the red flag from before the user's last message,"
+    " and that message gave you work."
+)
+OPEN_ITEMS_REASON = "The title '{title}' shows the work as done, and the task list has open items."
+ALL_ITEMS_COMPLETED_REASON = "The title '{title}' shows work running, and every task list item is completed or deleted."
+
 TURN_BLOCK_REASON = (
-    "This turn set no session title. Call {tool_name} now with '<emoji> <name>':"
+    "{why} Call {tool_name} now with '<emoji> <name>' for the current status:"
     " \U0001f6a9 the user must act, \U0001f6a7 an outside dependency blocks the work,"
     " \u2705 the work is done, \u23f3 work runs and nothing waits on the user."
     " When the tool is deferred, load its schema with ToolSearch first."
@@ -69,3 +82,8 @@ TURN_BLOCK_REASON = (
     " After the call, end the turn with one short closing sentence."
     " Leave the earlier reply as it stands and do not repeat it."
 )
+ALL_STALE_AT_START_STATUSES = frozenset({RED_FLAG_STATUS, CHECK_MARK_STATUS})
+TITLE_NUDGE_TEMPLATE = (
+    "The session title shows '{title}' from before this message. Set it with {tool_name} to"
+    " '⏳ <name>' before other work, so the user sees the session working."
+)

package/hooks/open_task_asks.py

@@ -1,67 +1,33 @@
-"""Per-session record of the user's prompts, read by the open tasks Stop gate.
+"""Tell a prompt that asks for work from one that does not.
 
-Every prompt lands in one file outside the task store::
-
-    ~/.claude/open-task-asks/<session id>.json
-    {"prompts": [{"text": "...", "recorded_at": 1761076800.0, "ask_id": "ask-1"}, ...]}
-
-A prompt that asks for work gets the next ``ask-N`` id. A question-only
-prompt, an acknowledgement such as ``thanks!``, an empty prompt, a prompt of only
-``<system-reminder>`` blocks, and an envelope such as ``<agent-message>`` or
-``<task-notification>`` get ``ask_id`` null, and the gate still reads their
-text when it checks the quote on a ``Dropped:`` line.
+The open tasks Stop gate, the session title gate, and the ask tracking nudge
+read a prompt through ``is_ask``. A question-only prompt, an acknowledgement
+such as ``thanks!``, an empty prompt, a prompt of only ``<system-reminder>``
+blocks, and an envelope such as ``<agent-message>`` or ``<task-notification>``
+ask for no work.
 """
 
 from __future__ import annotations
 
-import json
 import os
 import re
-import time
 from pathlib import Path
-from typing import NamedTuple
 
-from atomic_file_writer import write_text_atomically
 from hooks_constants.open_tasks_stop_gate_constants import (
     ACKNOWLEDGEMENT_PATTERN,
     ALL_ASK_ONLY_ENVELOPE_MARKERS,
-    ASK_ID_TEMPLATE,
-    ASK_PROMPT_ID_KEY,
-    ASK_PROMPT_RECORDED_AT_KEY,
-    ASK_PROMPT_TEXT_KEY,
-    ASKS_DIRECTORY_NAME,
-    ASKS_FILE_SUFFIX,
-    ASKS_PROMPTS_KEY,
-    ASKS_TEMPORARY_PREFIX,
-    ASKS_TEMPORARY_SUFFIX,
     CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE,
     CLAUDE_HOME_DIRECTORY_NAME,
     INTERROGATIVE_START_PATTERN,
     POLITE_REQUEST_START_PATTERN,
     QUESTION_END_PATTERN,
-    SAFE_SESSION_ID_PATTERN,
     SENTENCE_SPLIT_PATTERN,
     SYSTEM_REMINDER_BLOCK_PATTERN,
-    UTF8_ENCODING,
     YES_OR_NO_END_PATTERN,
 )
 from hooks_constants.spawn_readiness_hook_constants import ALL_HARNESS_ENVELOPE_MARKERS
 
 
-class RecordedPrompt(NamedTuple):
-    """One prompt the user sent.
-
-    Attributes:
-        text: The prompt as the user sent it, with ``<system-reminder>`` blocks removed.
-        recorded_at: Seconds since the epoch when the recorder saw it.
-        ask_id: ``ask-N`` for a prompt that asks for work, or None.
-    """
-
-    text: str
-    recorded_at: float
-    ask_id: str | None
-
-
 def claude_home() -> Path:
     """Return the Claude home directory, honoring ``CLAUDE_CONFIG_DIR``."""
     configured_directory = os.environ.get(CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE)
@@ -70,12 +36,6 @@ def claude_home() -> Path:
     return Path.home() / CLAUDE_HOME_DIRECTORY_NAME
 
 
-def _asks_file(session_id: object) -> Path | None:
-    if not isinstance(session_id, str) or not re.fullmatch(SAFE_SESSION_ID_PATTERN, session_id):
-        return None
-    return claude_home() / ASKS_DIRECTORY_NAME / (session_id + ASKS_FILE_SUFFIX)
-
-
 def is_question_only(prompt_text: str) -> bool:
     """Return True when the prompt asks a question and asks for no work.
 
@@ -122,58 +82,3 @@ def is_ask(prompt_text: str) -> bool:
     if re.fullmatch(ACKNOWLEDGEMENT_PATTERN, stripped_text, re.IGNORECASE):
         return False
     return not is_question_only(stripped_text)
-
-
-def recorded_prompts(session_id: object) -> list[RecordedPrompt]:
-    """Return every prompt recorded for the session, oldest first."""
-    asks_file = _asks_file(session_id)
-    if asks_file is None:
-        return []
-    try:
-        all_file_fields = json.loads(asks_file.read_text(encoding=UTF8_ENCODING))
-    except (OSError, ValueError):
-        return []
-    all_entries = (
-        all_file_fields.get(ASKS_PROMPTS_KEY) if isinstance(all_file_fields, dict) else None
-    )
-    if not isinstance(all_entries, list):
-        return []
-    return [
-        _parsed_prompt(each_entry) for each_entry in all_entries if isinstance(each_entry, dict)
-    ]
-
-
-def _parsed_prompt(all_entry_fields: dict[str, object]) -> RecordedPrompt:
-    recorded_at = all_entry_fields.get(ASK_PROMPT_RECORDED_AT_KEY)
-    ask_id = all_entry_fields.get(ASK_PROMPT_ID_KEY)
-    return RecordedPrompt(
-        str(all_entry_fields.get(ASK_PROMPT_TEXT_KEY, "")),
-        float(recorded_at) if isinstance(recorded_at, (int, float)) else 0.0,
-        ask_id if isinstance(ask_id, str) else None,
-    )
-
-
-def record_prompt(session_id: object, prompt_text: str) -> str | None:
-    """Append the prompt to the session's file and return its ``ask-N`` id, or None for no ask."""
-    asks_file = _asks_file(session_id)
-    if asks_file is None:
-        return None
-    all_prompts = recorded_prompts(session_id)
-    ask_count = sum(1 for each_prompt in all_prompts if each_prompt.ask_id)
-    ask_id = ASK_ID_TEMPLATE.format(ask_number=ask_count + 1) if is_ask(prompt_text) else None
-    all_prompts.append(RecordedPrompt(prompt_without_reminders(prompt_text), time.time(), ask_id))
-    serialized_text = json.dumps(
-        {ASKS_PROMPTS_KEY: [each_prompt._asdict() for each_prompt in all_prompts]}
-    )
-    try:
-        write_text_atomically(
-            asks_file,
-            serialized_text,
-            UTF8_ENCODING,
-            ASKS_TEMPORARY_PREFIX,
-            ASKS_TEMPORARY_SUFFIX,
-            False,
-        )
-    except OSError:
-        return None
-    return ask_id

package/hooks/session/test_tracking_nudge.py

@@ -0,0 +1,124 @@
+import importlib
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+_SESSION_DIR = Path(__file__).resolve().parent
+if str(_SESSION_DIR) not in sys.path:
+    sys.path.insert(0, str(_SESSION_DIR))
+
+tracking_nudge = importlib.import_module("tracking_nudge")
+
+NUDGE_PATH = _SESSION_DIR / "tracking_nudge.py"
+TITLE_TOOL = "mcp__claude-code-remote__set_session_title"
+TOOL_LISTING = {"type": "attachment", "attachment": {"tools": [{"name": TITLE_TOOL}]}}
+
+
+def titled_entries(title: str) -> list[dict[str, object]]:
+    title_use = {"type": "tool_use", "id": "t1", "name": TITLE_TOOL, "input": {"title": title}}
+    title_done = {"type": "tool_result", "tool_use_id": "t1", "content": "ok"}
+    return [
+        TOOL_LISTING,
+        {"type": "assistant", "message": {"content": [title_use]}},
+        {"type": "user", "message": {"content": [title_done]}},
+    ]
+
+
+def run_nudge(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    prompt_text: str,
+    all_entries: list[dict[str, object]],
+) -> str:
+    transcript_path = tmp_path / "s.jsonl"
+    transcript_path.write_text(
+        "\n".join(json.dumps(each) for each in all_entries), encoding="utf-8"
+    )
+    hook_input = {
+        "hook_event_name": "UserPromptSubmit",
+        "prompt": prompt_text,
+        "transcript_path": str(transcript_path),
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    assert tracking_nudge.main() == 0
+    printed_output = capsys.readouterr().out
+    return (
+        json.loads(printed_output)["hookSpecificOutput"]["additionalContext"]
+        if printed_output
+        else ""
+    )
+
+
+def test_should_remind_a_work_prompt_to_use_the_task_list(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    context_text = run_nudge(
+        monkeypatch, capsys, tmp_path, "Export the APKs", titled_entries("⏳ Export")
+    )
+    assert "TaskCreate" in context_text
+    assert "⏳ Export" not in context_text
+
+
+@pytest.mark.parametrize("earlier_title", ["\U0001f6a9 Merge approval", "✅ Gate"])
+def test_should_ask_to_refresh_a_title_that_says_the_session_waits_or_is_done(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    earlier_title: str,
+) -> None:
+    context_text = run_nudge(
+        monkeypatch, capsys, tmp_path, "Export the APKs", titled_entries(earlier_title)
+    )
+    assert earlier_title in context_text
+    assert TITLE_TOOL in context_text
+
+
+@pytest.mark.parametrize(
+    "prompt_text",
+    ["did the export fail?", "thanks!", "<task-notification>done</task-notification>"],
+)
+def test_should_stay_silent_for_a_prompt_that_asks_for_no_work(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: Path,
+    prompt_text: str,
+) -> None:
+    assert (
+        run_nudge(
+            monkeypatch, capsys, tmp_path, prompt_text, titled_entries("\U0001f6a9 Merge approval")
+        )
+        == ""
+    )
+
+
+def test_should_skip_the_title_note_in_a_session_without_the_title_tool() -> None:
+    assert tracking_nudge.title_nudge([]) is None
+    assert tracking_nudge.title_nudge(titled_entries("✅ Gate")) is not None
+
+
+def test_should_build_the_note_only_for_a_work_prompt() -> None:
+    assert tracking_nudge.ask_tracking_context("did it fail?", []) is None
+    assert "task list" in (tracking_nudge.ask_tracking_context("Export the APKs", []) or "")
+
+
+def test_should_print_the_documented_output_through_a_subprocess(tmp_path: Path) -> None:
+    hook_input = {"hook_event_name": "UserPromptSubmit", "prompt": "Export the APKs"}
+    completed_process = subprocess.run(
+        [sys.executable, str(NUDGE_PATH)],
+        input=json.dumps(hook_input),
+        capture_output=True,
+        text=True,
+        env={"HOME": str(tmp_path), "USERPROFILE": str(tmp_path), "PATH": ""},
+        check=False,
+    )
+    assert completed_process.returncode == 0
+    hook_output = json.loads(completed_process.stdout)["hookSpecificOutput"]
+    assert hook_output["hookEventName"] == "UserPromptSubmit"
+    assert "TaskCreate" in hook_output["additionalContext"]

package/hooks/session/tracking_nudge.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook that reminds the agent to track a new ask before it starts.
+
+The user follows a session in two places: the task list shows what the agent
+does, and the title's status emoji shows whether the session needs them. A new
+ask changes both, so the hook adds one short ``additionalContext`` note when the
+prompt asks for work::
+
+    "Export the APKs"                        -> task list note
+    "Export the APKs", title shows a red flag or a check mark
+                                             -> task list note + title note
+    "did the export fail?"                   -> nothing
+    "<task-notification>...</task-notification>"
+                                             -> nothing
+
+The note never blocks. The Stop gates ``open_tasks_stop_gate.py`` and
+``session_title_turn_gate.py`` hold the turn once only when the agent skipped it.
+The title note needs the title tool in the transcript, as the title gate does.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+blocking_directory = str(Path(__file__).resolve().parent.parent / "blocking")
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from hooks_constants.open_tasks_stop_gate_constants import (
+    ALLOW_EXIT_CODE,
+    PROMPT_KEY,
+    PROMPT_SUBMIT_EVENT_NAME,
+    TASK_LIST_NUDGE,
+    TRANSCRIPT_PATH_KEY,
+    WORD_SEPARATOR,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.session_title_constants import (
+    ALL_STALE_AT_START_STATUSES,
+    TITLE_NUDGE_TEMPLATE,
+    TITLE_TOOL_DISPLAY_SEPARATOR,
+)
+from open_task_asks import is_ask
+from session_title_turn_gate import (
+    available_title_tools,
+    read_transcript_entries,
+    shown_title,
+    title_status,
+)
+
+
+def title_nudge(all_entries: list[dict[str, object]]) -> str | None:
+    """Return the title note when the shown title says the session waits or is done, else None.
+
+    ::
+
+        title tool listed, shows "\U0001f6a9 Merge approval"   -> note naming that title
+        title tool listed, shows "⏳ Export"               -> None
+        no title tool in the transcript                         -> None
+
+    Args:
+        all_entries: The transcript entries, oldest first.
+
+    Returns:
+        The note text, or None.
+    """
+    all_title_tools = available_title_tools(all_entries)
+    title = shown_title(all_entries)
+    if (
+        not all_title_tools
+        or title is None
+        or title_status(title) not in ALL_STALE_AT_START_STATUSES
+    ):
+        return None
+    return TITLE_NUDGE_TEMPLATE.format(
+        title=title, tool_name=TITLE_TOOL_DISPLAY_SEPARATOR.join(all_title_tools)
+    )
+
+
+def ask_tracking_context(prompt_text: str, all_entries: list[dict[str, object]]) -> str | None:
+    """Return the note for a prompt that asks for work, or None for any other prompt."""
+    if not is_ask(prompt_text):
+        return None
+    all_notes = [TASK_LIST_NUDGE, title_nudge(all_entries)]
+    return WORD_SEPARATOR.join(each_note for each_note in all_notes if each_note)
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    prompt_value = hook_input.get(PROMPT_KEY) if hook_input is not None else None
+    if hook_input is None or not isinstance(prompt_value, str):
+        return ALLOW_EXIT_CODE
+    context_text = ask_tracking_context(
+        prompt_value, read_transcript_entries(hook_input.get(TRANSCRIPT_PATH_KEY))
+    )
+    if context_text:
+        hook_output = {
+            "hookSpecificOutput": {
+                "hookEventName": PROMPT_SUBMIT_EVENT_NAME,
+                "additionalContext": context_text,
+            }
+        }
+        sys.stdout.write(json.dumps(hook_output))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())