claude-dev-env 8.117.1 → 8.117.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,384 @@
1
+ """Find the words in a reply or a sent file that say something waits on the user.
2
+
3
+ The open tasks Stop gate reads the closing reply and each text file the turn
4
+ sent through this module::
5
+
6
+ flag: Three items need you. -> "need you"
7
+ flag: The docs pull request needs your merge. -> "needs your"
8
+ flag: Say when the demo sessions may be archived. -> "Say when"
9
+ flag: It isn't merged yet and needs your approval. -> "needs your"
10
+ flag: Pull request 12 (not urgent) needs your approval.
11
+ ok: Nothing here needs you.
12
+ ok: None of the open items needs you.
13
+ ok: This change does not need you.
14
+ ok: Action required: none.
15
+ ok: The docs say when the token expires.
16
+ ok: The label reads `needs you`. (a code span)
17
+ ok: > What needs you? (a quote)
18
+
19
+ The rule behind every shape below: a wrong hold costs the agent one step, and
20
+ a wrong skip hides a step from the user. So an unclear line is held, and a
21
+ match is skipped only in the shapes this text names.
22
+
23
+ A match is skipped when its clause negates it. The clause is the text before
24
+ the match on the same line, back to a sentence mark, a comma, a semicolon, a
25
+ colon, a table bar, or one of the words and, but, so, then, and while. The read
26
+ looks 240 characters back for it. A line break always ends a clause, so
27
+ "Nothing on this list" wrapped onto "needs you." is held. A carriage return
28
+ counts as a line break. A paragraph that holds another character that ends a
29
+ line for ``str.splitlines``, such as a form feed or U+2028, is held at every
30
+ match, since readers do not agree on where its lines end.
31
+
32
+ The clause is read as words. A word is a run of characters with white space,
33
+ or an end of the paragraph, on each side. It counts only when all of it sits
34
+ inside the clause and it ends before the match. The asterisks and underscores
35
+ at its two ends are removed, and the rest must equal a negating word. So
36
+ "**No** item needs you." is skipped, and "No-reply inbox needs your record",
37
+ "(Nothing here needs you.)", and "Nothing*needs you." are held. Three shapes
38
+ negate a match:
39
+
40
+ - nothing, none, or nobody anywhere in the clause;
41
+ - no, neither, or nor as the first word of the clause, also after "there is",
42
+ "there are", "there was", or "there were";
43
+ - not, never, without, "no longer", or a word ending in n't (with a straight
44
+ or a curly apostrophe), with up to three words between it and the match.
45
+
46
+ The first word of a clause is the first one after its markers. A marker is a
47
+ word that holds only hyphens, plus signs, hash marks, greater-than signs,
48
+ digits, parentheses, and square brackets, or nothing, once the emphasis marks
49
+ at its ends are removed, as in "- [ ] No open item needs you." and
50
+ "**1)** No reviewer needs your approval." When the 240 characters hold no clause break
51
+ and do not reach the start of the paragraph, the clause start is out of view.
52
+ Then the second shape does not apply and "say when" does not count.
53
+
54
+ A match is skipped too when it is a label with nothing under it. The label
55
+ form is closed, it sits on one line, and it reads in this order::
56
+
57
+ the match Action required
58
+ a colon or a dash :
59
+ none, nothing, n/a, none
60
+ "no action", "no actions",
61
+ "no step", or "no steps"
62
+ then, when present: needed, at this time
63
+ required, "for now",
64
+ "at this time", or "right now"
65
+ then, when present: one full .
66
+ stop, exclamation mark, or
67
+ question mark
68
+ the end of the line
69
+
70
+ Up to eight spaces, tabs, or Markdown emphasis marks may sit on each side of
71
+ the colon or dash, and up to three emphasis marks on each side of the closing
72
+ mark, as in ``**Action required:** none.`` Every other wording after a match is
73
+ held: "Action required: NO_PROXY must list the host", "blocked on you - nothing
74
+ else is holding it", "Action required: none. Merge item 12 first.", "Action
75
+ required: no", where a bare no can be an answer or an abbreviation, a
76
+ "What needs you" heading over a paragraph that says "Nothing.", and a match
77
+ that a line break splits, as in "Action" on one line and "required: none." on
78
+ the next.
79
+
80
+ "Say when" counts only at the start of its clause, where it is an instruction.
81
+ The words before it are read with the marker characters, full stops, and
82
+ emphasis marks at their ends removed. A word with no letter left is passed
83
+ over, and the rest must be nothing, the word please, the word just, or both
84
+ in that order, read with case folding. So "- [ ] Say when" counts, and "- [x] Say when" and "The docs
85
+ say when" do not. That rule covers "say" with white space right after it. With
86
+ an emphasis mark or the closing part of a link right after "say", the phrase
87
+ counts wherever it sits, as in "The docs **say** when" and "- [x] [Say](link)
88
+ when".
89
+
90
+ The words of a phrase are joined by white space. Up to three asterisks,
91
+ underscores, or opening square brackets may sit on each side of that white
92
+ space, so "needs **your** approval" and "waiting on [you](link)" count, and so
93
+ does "_needs your_ merge". The closing part of a link may sit before the white
94
+ space too. That part is a closing square bracket, alone or with a target in
95
+ parentheses or a label in square brackets after it, and then up to three
96
+ asterisks or underscores. So "[needs](link) your approval", "[needs][1] your
97
+ approval", and "**[You](link)** need to" count. The target or label holds no
98
+ white space and at most 256 characters. A target ends at its first closing
99
+ parenthesis, and a label at its first closing square bracket. So a link with
100
+ a title, as in ``[needs](link "title") your``, breaks the phrase, and so does
101
+ a target with parentheses inside it, as in
102
+ ``[needs](https://example.com/A_(b)) your``, or a label with square brackets
103
+ inside it. Every place a phrase can
104
+ start is read, also inside another phrase. In Markdown an inline HTML tag or a
105
+ character entity between two words of a phrase breaks it.
106
+
107
+ These shapes read words. They do not read grammar, so a line can hold a
108
+ negating word in the same clause and still hand over a step, and that line is
109
+ skipped. The gate reads the whole reply and every sent file, and one phrase
110
+ outside the shapes is enough to hold the turn.
111
+
112
+ Fences, HTML blocks, quoted paragraphs, and code spans are left out of Markdown
113
+ and plain text first, and each paragraph is read on its own. A code span reads
114
+ as a space between the words of a phrase. Everywhere else it reads as U+FFFC,
115
+ a character that is no letter and no white space, and one in the text itself
116
+ reads the same way. A match is held when a run of characters with no white
117
+ space holds that character joined to others, as in ``Not`-`e`` and "api`/`web".
118
+ That rule comes before the three negating shapes and the "say when" rule, so
119
+ it holds a match they would skip. The label form is read first, so a joined
120
+ run before "Action required: none." leaves it skipped. The runs are read in
121
+ the text the match looks back over: from the last clause break, or from 240
122
+ characters back when no break is that near, up to the match. So the part of a
123
+ word after a full stop counts, as in ``Done.`x`a No item needs you.``, and so
124
+ does a word that touches the match, as in ``It isn't a b c d`x`needs you.``
125
+ The asterisks and underscores at the two ends of a run are removed first, so
126
+ ``No **`x`** item needs you.`` is skipped. The label form does not reach
127
+ across a code span, so "Action required: none." with a code span after it is
128
+ held.
129
+
130
+ An HTML file is read as its text, one block at a time, with every tag removed
131
+ and the contents of script, style, template, title, textarea, noscript, code,
132
+ pre, and blockquote elements left out. White space in the HTML source counts
133
+ as one space, a ``br`` as a line break, and an inline ``code`` element as
134
+ U+FFFC. Each block is read a second time with that character removed, so a
135
+ phrase that a ``code`` element splits still counts. A U+FFFC in the page text
136
+ itself is read as U+FFFD, which no reading removes. A hidden attribute and a style that hides an element are not read, so
137
+ that text still counts.
138
+ """
139
+
140
+ from __future__ import annotations
141
+
142
+ import itertools
143
+ import re
144
+ import sys
145
+ from collections.abc import Iterable
146
+ from html.parser import HTMLParser
147
+ from pathlib import Path
148
+
149
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
150
+ if hooks_root_directory not in sys.path:
151
+ sys.path.insert(0, hooks_root_directory)
152
+
153
+ from final_reply_gate import prose_paragraphs_with_code_as
154
+ from hooks_constants.open_tasks_stop_gate_constants import UTF8_ENCODING
155
+ from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
156
+ from hooks_constants.user_step_wording_constants import (
157
+ ALL_ABSENCE_WORDS,
158
+ ALL_CLAUSE_OPENING_NEGATORS,
159
+ ALL_CONTRACTED_NEGATOR_ENDINGS,
160
+ ALL_HTML_FILE_SUFFIXES,
161
+ ALL_HTML_HIDDEN_TAGS,
162
+ ALL_HTML_INLINE_TAGS,
163
+ ALL_INSTRUCTION_OPENERS,
164
+ ALL_LATE_NEGATORS,
165
+ ALL_SENT_TEXT_FILE_SUFFIXES,
166
+ ALL_THERE_VERBS,
167
+ BARE_IMPERATIVE_PATTERN,
168
+ BINARY_READ_MODE,
169
+ CLAUSE_BREAK_PATTERN,
170
+ CLAUSE_LEAD_WINDOW_CHARACTERS,
171
+ CLAUSE_WORD_PATTERN,
172
+ CODE_SPAN_SPACE,
173
+ CODE_SPAN_STAND_IN,
174
+ EMPHASIS_MARKS,
175
+ HTML_BLOCK_SEPARATOR,
176
+ HTML_LINE_BREAK_TAG,
177
+ HTML_LITERAL_STAND_IN_TEXT,
178
+ HTML_SOURCE_SPACE,
179
+ HTML_SOURCE_SPACE_PATTERN,
180
+ LINE_BREAK,
181
+ LINE_ENDING_PATTERN,
182
+ MARKER_WORD_PATTERN,
183
+ MAXIMUM_SENT_FILE_BYTES,
184
+ MAXIMUM_WORDS_AFTER_LATE_NEGATOR,
185
+ OPENER_MARKER_CHARACTERS,
186
+ NEGATED_TAIL_PATTERN,
187
+ ODD_LINE_END_PATTERN,
188
+ PHRASE_GROUP,
189
+ ALL_NO_LONGER_WORDS,
190
+ THERE_WORD,
191
+ USER_STEP_PATTERN,
192
+ WORD_RUN_PATTERN,
193
+ )
194
+
195
+
196
+ def waiting_phrase_in_prose(prose_text: str) -> str | None:
197
+ """Return the first phrase in the prose that says something waits on the user, or None.
198
+
199
+ ::
200
+
201
+ >>> waiting_phrase_in_prose("The key is set. Two items need you.")
202
+ 'need you'
203
+ >>> waiting_phrase_in_prose("Nothing else is waiting on you.") is None
204
+ True
205
+
206
+ Each match looks back over a fixed window for its clause, so a long text
207
+ reads in time that grows with its length.
208
+ """
209
+ clause_text = LINE_ENDING_PATTERN.sub(LINE_BREAK, prose_text)
210
+ phrase_text = clause_text.replace(CODE_SPAN_STAND_IN, CODE_SPAN_SPACE)
211
+ has_odd_line_end = ODD_LINE_END_PATTERN.search(clause_text) is not None
212
+ for each_match in USER_STEP_PATTERN.finditer(phrase_text):
213
+ if has_odd_line_end or _hands_over_a_step(clause_text, each_match):
214
+ return each_match.group(PHRASE_GROUP)
215
+ return None
216
+
217
+
218
+ def _clause_start(prose_text: str, phrase_start: int) -> tuple[int, bool]:
219
+ window_start = max(0, phrase_start - CLAUSE_LEAD_WINDOW_CHARACTERS)
220
+ all_break_ends = [
221
+ each_break.end() for each_break in CLAUSE_BREAK_PATTERN.finditer(prose_text, window_start, phrase_start)
222
+ ]
223
+ if all_break_ends:
224
+ return all_break_ends[-1], True
225
+ return window_start, window_start == 0
226
+
227
+
228
+ def _clause_words(prose_text: str, clause_start: int, phrase_start: int) -> list[str]:
229
+ return [
230
+ each_word.group().strip(EMPHASIS_MARKS).lower()
231
+ for each_word in CLAUSE_WORD_PATTERN.finditer(prose_text, clause_start, phrase_start)
232
+ if each_word.end() < phrase_start
233
+ ]
234
+
235
+
236
+ def _holds_a_negator(all_clause_words: list[str]) -> bool:
237
+ if not ALL_ABSENCE_WORDS.isdisjoint(all_clause_words):
238
+ return True
239
+ all_late_words = all_clause_words[-(MAXIMUM_WORDS_AFTER_LATE_NEGATOR + 1) :]
240
+ if any(
241
+ each_word in ALL_LATE_NEGATORS or each_word.endswith(ALL_CONTRACTED_NEGATOR_ENDINGS)
242
+ for each_word in all_late_words
243
+ ):
244
+ return True
245
+ all_no_longer_reach = all_clause_words[-(MAXIMUM_WORDS_AFTER_LATE_NEGATOR + len(ALL_NO_LONGER_WORDS)) :]
246
+ return ALL_NO_LONGER_WORDS in itertools.pairwise(all_no_longer_reach)
247
+
248
+
249
+ def _opens_with_a_negator(all_clause_words: list[str]) -> bool:
250
+ all_lead_words = itertools.dropwhile(MARKER_WORD_PATTERN.fullmatch, all_clause_words)
251
+ first_word = next(all_lead_words, None)
252
+ if first_word == THERE_WORD and next(all_lead_words, None) in ALL_THERE_VERBS:
253
+ first_word = next(all_lead_words, None)
254
+ return first_word in ALL_CLAUSE_OPENING_NEGATORS
255
+
256
+
257
+ def _opens_an_instruction(all_clause_words: list[str]) -> bool:
258
+ all_bare_words = (each_word.strip(OPENER_MARKER_CHARACTERS).casefold() for each_word in all_clause_words)
259
+ all_lettered_words = tuple(each_word for each_word in all_bare_words if any(map(str.isalpha, each_word)))
260
+ return all_lettered_words in ALL_INSTRUCTION_OPENERS
261
+
262
+
263
+ def _holds_a_joined_code_span(prose_text: str, clause_start: int, phrase_start: int) -> bool:
264
+ all_word_runs = (
265
+ each_run.strip(EMPHASIS_MARKS) for each_run in WORD_RUN_PATTERN.findall(prose_text, clause_start, phrase_start)
266
+ )
267
+ return any(CODE_SPAN_STAND_IN in each_run and each_run.strip(CODE_SPAN_STAND_IN) for each_run in all_word_runs)
268
+
269
+
270
+ def _hands_over_a_step(clause_text: str, phrase_match: re.Match[str]) -> bool:
271
+ phrase_start = phrase_match.start(PHRASE_GROUP)
272
+ phrase = phrase_match.group(PHRASE_GROUP)
273
+ is_phrase_on_one_line = LINE_BREAK not in phrase
274
+ if is_phrase_on_one_line and NEGATED_TAIL_PATTERN.match(clause_text, phrase_match.end(PHRASE_GROUP)):
275
+ return False
276
+ clause_start, is_clause_start_in_view = _clause_start(clause_text, phrase_start)
277
+ if _holds_a_joined_code_span(clause_text, clause_start, phrase_start):
278
+ return True
279
+ all_clause_words = _clause_words(clause_text, clause_start, phrase_start)
280
+ if _holds_a_negator(all_clause_words):
281
+ return False
282
+ is_bare_imperative = BARE_IMPERATIVE_PATTERN.match(phrase) is not None
283
+ if not is_clause_start_in_view:
284
+ return not is_bare_imperative
285
+ if _opens_with_a_negator(all_clause_words):
286
+ return False
287
+ return not is_bare_imperative or _opens_an_instruction(all_clause_words)
288
+
289
+
290
+ def waiting_phrase(shown_text: str) -> str | None:
291
+ """Return the first phrase in Markdown or plain text that says something waits on the user, or None."""
292
+ line_fed_text = LINE_ENDING_PATTERN.sub(LINE_BREAK, shown_text)
293
+ return _first_waiting_phrase(prose_paragraphs_with_code_as(line_fed_text, CODE_SPAN_STAND_IN))
294
+
295
+
296
+ def _first_waiting_phrase(all_blocks: Iterable[str]) -> str | None:
297
+ all_phrases = (waiting_phrase_in_prose(each_block) for each_block in all_blocks)
298
+ return next((each_phrase for each_phrase in all_phrases if each_phrase is not None), None)
299
+
300
+
301
+ class _VisibleTextParser(HTMLParser):
302
+ def __init__(self) -> None:
303
+ super().__init__(convert_charrefs=True)
304
+ self.all_text_runs: list[str] = []
305
+ self.hidden_depth = 0
306
+
307
+ def handle_starttag(self, tag: str, all_attributes: list[tuple[str, str | None]]) -> None:
308
+ if tag in ALL_HTML_HIDDEN_TAGS:
309
+ self.hidden_depth += 1
310
+ if tag in ALL_HTML_HIDDEN_TAGS and tag in ALL_HTML_INLINE_TAGS:
311
+ self.all_text_runs.append(CODE_SPAN_STAND_IN)
312
+ if tag == HTML_LINE_BREAK_TAG:
313
+ self.all_text_runs.append(LINE_BREAK)
314
+ elif tag not in ALL_HTML_INLINE_TAGS:
315
+ self.all_text_runs.append(HTML_BLOCK_SEPARATOR)
316
+
317
+ def handle_endtag(self, tag: str) -> None:
318
+ if tag in ALL_HTML_HIDDEN_TAGS and self.hidden_depth:
319
+ self.hidden_depth -= 1
320
+ if tag != HTML_LINE_BREAK_TAG and tag not in ALL_HTML_INLINE_TAGS:
321
+ self.all_text_runs.append(HTML_BLOCK_SEPARATOR)
322
+
323
+ def handle_data(self, data: str) -> None:
324
+ if not self.hidden_depth:
325
+ shown_data = data.replace(CODE_SPAN_STAND_IN, HTML_LITERAL_STAND_IN_TEXT)
326
+ self.all_text_runs.append(HTML_SOURCE_SPACE_PATTERN.sub(HTML_SOURCE_SPACE, shown_data))
327
+
328
+
329
+ def html_visible_text(page_markup: str) -> str:
330
+ """Return the text of an HTML page, with its tags removed.
331
+
332
+ ::
333
+
334
+ <h2>What needs you</h2><p>Add the <b>key</b>.</p> -> "What needs you", "Add the key."
335
+ <script>var needsYou = 1</script> -> nothing
336
+ <code>needs you</code> -> nothing
337
+
338
+ Script, style, template, title, textarea, noscript, code, pre, and
339
+ blockquote contents are left out. A tag that is not an inline tag leaves a
340
+ blank line, so a heading and the paragraph after it stay apart, and
341
+ ``file_waiting_phrase`` reads each such block on its own. White space in
342
+ the source becomes one space, and a ``br`` leaves a line break. Text under
343
+ a hidden attribute or a hiding style is kept.
344
+ """
345
+ return _html_text_with_code_marks(page_markup).replace(CODE_SPAN_STAND_IN, "")
346
+
347
+
348
+ def _html_text_with_code_marks(page_markup: str) -> str:
349
+ text_parser = _VisibleTextParser()
350
+ text_parser.feed(page_markup)
351
+ text_parser.close()
352
+ return "".join(text_parser.all_text_runs)
353
+
354
+
355
+ def file_waiting_phrase(file_path_text: str, working_directory: object) -> str | None:
356
+ """Return the first waiting phrase in a text file the turn sent to the user, or None.
357
+
358
+ A path that is not absolute is read from the working directory. A file with
359
+ another suffix, a path that is no regular file (a pipe, a device, a
360
+ directory), a file over the size limit, and a file that cannot be read give
361
+ None. The read stops one byte past the size limit.
362
+ """
363
+ file_path = Path(file_path_text)
364
+ if not file_path.is_absolute() and isinstance(working_directory, str):
365
+ file_path = Path(working_directory) / file_path
366
+ file_suffix = file_path.suffix.lower()
367
+ if file_suffix not in ALL_SENT_TEXT_FILE_SUFFIXES:
368
+ return None
369
+ try:
370
+ if not file_path.is_file():
371
+ return None
372
+ with file_path.open(BINARY_READ_MODE) as sent_file:
373
+ file_bytes = sent_file.read(MAXIMUM_SENT_FILE_BYTES + 1)
374
+ except (OSError, ValueError):
375
+ return None
376
+ if len(file_bytes) > MAXIMUM_SENT_FILE_BYTES:
377
+ return None
378
+ file_text = file_bytes.decode(UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
379
+ if file_suffix in ALL_HTML_FILE_SUFFIXES:
380
+ all_blocks = _html_text_with_code_marks(file_text).split(HTML_BLOCK_SEPARATOR)
381
+ return _first_waiting_phrase(
382
+ each_reading for each_block in all_blocks for each_reading in (each_block, each_block.replace(CODE_SPAN_STAND_IN, ""))
383
+ )
384
+ return waiting_phrase(file_text)
@@ -5,7 +5,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
5
5
  ## Checks
6
6
 
7
7
  - `blocking/final_reply_gate.py` checks the reply a session ends its turn with. Its `windows_path_violation` blocks a path the terminal would render without one of its backslashes. Its `unbriefed_question_violation` blocks a reply whose last paragraph, with fences, quotes, and code spans left out, ends with a question mark or says a question still stands, when the turn sent no `AskUserQuestion`, hearthbot decision card, or Codex `request_user_input` call; it is skipped when the transcript cannot be read.
8
- - `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.
8
+ - `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 also holds the turn once when completed items sit beside open ones on the task list the user sees: the session's task store, or the transcript's list when the session has no store. A list that `CLAUDE_CODE_TASK_LIST_ID` shares with other sessions is left alone. It also holds the turn once when the closing reply, or a Markdown, text, or HTML file the turn sent with `SendUserFile`, says something waits on the user and the turn ran no read call or sent no question tool call. `blocking/user_step_wording.py` finds that wording: phrases such as "needs you", "waiting on you", "you need to", and "say when", outside fences, quotes, and code spans, unless a negation on the same line covers the phrase ("Nothing here needs you", "This change does not need you") or the phrase is a label with nothing under it ("Action required: none."). The module docstring of `blocking/user_step_wording.py` names each skip shape. Every other wording is held, because a wrong hold costs the agent one step and a wrong skip hides a step from the user. "Say when" counts only at the start of its clause. Markdown and plain text are read one paragraph at a time. In an HTML file it reads the text one block at a time, counts white space in the source as one space and a `br` as a line break, and leaves out the contents of `script`, `style`, `template`, `title`, `textarea`, `noscript`, `code`, `pre`, and `blockquote` elements; text under a hidden attribute still counts. It skips a sent path that is no regular file and a file over 256 KB, and reads a path sent twice once. A read call is a shell, a file or web read, a subagent, a Codex `local_shell_call`, or a tool whose name carries a read word such as `get`, `list`, or `read` and no write word such as `update` or `append`. Only the part of an MCP tool name after the server is read, and it is split into words at underscores, hyphens, and a capital that follows a lower-case letter or a digit. `TaskList`, `TaskGet`, `ToolSearch`, and the question tools do not count. The gate checks that a read ran and leaves which item it read to the agent, so each such hold tells the agent to read the live state of every item it shows as open, and to end the turn when the wording hands the user no step. One reason carries every finding. `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.
9
9
  - `session/tracking_nudge.py` adds one `additionalContext` note to a prompt that asks for work. The note asks for an item in the session's task list tool. It shows on the session's first ask and on the first ask after each compaction, through `once_per_session.py`. When the title shows the red flag or the check mark, it also asks for the hourglass before other work. In a session that has a `__set_session_title` tool and no title yet, it asks once for a first title in the `⏳ <name>` form, and never again in that session, compactions included, through `once_per_session.claim_only_showing`. `session_title_transcript.py` reads the title tool and the shown title from the transcript. It never blocks. No hook holds the end of a turn for the title.
10
10
  - `session/background_silence_prompt.py` adds one `additionalContext` note to a background event prompt, one that starts with `<task-notification>` or opens itself or a `<system-reminder>` block with `[SYSTEM NOTIFICATION - NOT USER INPUT]`, while the user asked for silence. The newest user-typed message that sets silence ("silent unless", "stay silent", "silent on updates", "no updates unless") or lifts it ("you can talk again", "updates are fine", "stop being silent") decides. The note quotes the user's "unless" or "except" clause word for word, or the whole message when it has no such clause, and says to end the turn with no text unless that exception applies now. Envelope prompts, compaction summaries, and quoted `>` lines are not the user's words. It never blocks.
11
11
  - 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 every claim, numbered in one refusal, 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 plain claims 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.
@@ -53,7 +53,7 @@ PARAGRAPH_SEPARATOR = "\n\n"
53
53
  BACKSLASH = "\\"
54
54
  BACKSLASHES_PER_LITERAL = 2
55
55
  MASKED_CODE_TEXT = " "
56
- FENCE_OPENER_PATTERN = re.compile(r"^ {0,3}(?:(`{3,})[^`\n]*|(~{3,})[^\n]*)\n", re.MULTILINE)
56
+ FENCE_OPENER_PATTERN = re.compile(r"^ {0,3}(?:(`{3,})[^`\n]*|(~{3,})(?!~)[^\n]*)\n", re.MULTILINE)
57
57
  FENCE_CLOSER_PREFIX = r"^ {0,3}"
58
58
  FENCE_CLOSER_SUFFIX = r"*[ \t]*$"
59
59
  WINDOWS_PATH_MESSAGE = (
@@ -106,16 +106,69 @@ ALL_QUESTION_TOOL_NAMES = frozenset(
106
106
  }
107
107
  )
108
108
  SESSION_TITLE_TOOL_SUFFIX = "__set_session_title"
109
- ALL_CODEX_TOOL_CALL_TYPES = frozenset({CODEX_FUNCTION_CALL_TYPE, "custom_tool_call", "local_shell_call"})
110
- BLOCK_REASON = (
109
+ CODEX_LOCAL_SHELL_CALL_TYPE = "local_shell_call"
110
+ ALL_CODEX_TOOL_CALL_TYPES = frozenset({CODEX_FUNCTION_CALL_TYPE, "custom_tool_call", CODEX_LOCAL_SHELL_CALL_TYPE})
111
+ UNTRACKED_WORK_REASON = (
111
112
  "This turn worked on the user's ask and left the task list unchanged. The user follows your work"
112
113
  " there. Update it now: TaskCreate the ask if it has no item, and TaskUpdate each item to its"
113
- " current status (TodoWrite or update_plan where that is the tracker). Then end the turn. Leave"
114
- " the reply as it stands."
114
+ " current status (TodoWrite or update_plan where that is the tracker)."
115
115
  )
116
+ COMPLETED_ITEMS_REASON_TEMPLATE = (
117
+ "The task list shows completed work beside open items ({completed_count} of {item_count} items"
118
+ " are completed). The user reads that list to see what is open. Remove each completed item now:"
119
+ " TaskUpdate with status deleted (TodoWrite or update_plan: send the list without it)."
120
+ )
121
+ KEEP_REPLY_INSTRUCTION = "Then end the turn. Leave the reply as it stands."
122
+ USER_STEP_LEAD_TEMPLATE = (
123
+ 'This turn tells the user that something waits on them ("{phrase}"). An item can close while it'
124
+ " sits on a list, so in this turn read the live state of each item you show as open: the pull"
125
+ " request, the session, the setting, or the log. Drop each one that is done, and show the user"
126
+ " only what still stands open."
127
+ )
128
+ UNREAD_STEP_REASON = "The turn ran no read call."
129
+ UNASKED_STEP_REASON = (
130
+ "The turn sent no question through the native question tool. Hand over each step on its own"
131
+ " through AskUserQuestion (Codex: request_user_input), one step per question: one short sentence"
132
+ " on what the step does, with the command block to paste or the link to open inside the"
133
+ " question. Keep long guides out of it. Where the host has no question tool, give each step its"
134
+ " own short paragraph with its block or link."
135
+ )
136
+ NO_STEP_INSTRUCTION = "When the wording hands the user no step, end the turn and leave the reply as it stands."
137
+ WORKING_DIRECTORY_KEY = "cwd"
138
+ SENT_FILES_KEY = "files"
139
+ ALL_READ_TOOL_NAMES = frozenset(
140
+ {
141
+ "Bash",
142
+ "PowerShell",
143
+ "Shell",
144
+ "shell",
145
+ "shell_command",
146
+ "exec_command",
147
+ "Read",
148
+ "Grep",
149
+ "Glob",
150
+ "WebFetch",
151
+ "WebSearch",
152
+ "Agent",
153
+ "Task",
154
+ }
155
+ )
156
+ ALL_READ_WORDS = frozenset(
157
+ {"get", "list", "read", "view", "search", "fetch", "query", "describe", "status", "log", "logs", "diff", "show"}
158
+ )
159
+ ALL_WRITE_WORDS = frozenset(
160
+ {
161
+ "update", "set", "create", "delete", "write", "append", "add", "remove", "send", "post", "edit",
162
+ "put", "patch", "save", "insert", "reset", "apply", "replace",
163
+ }
164
+ )
165
+ TOOL_NAME_SERVER_SEPARATOR = "__"
166
+ RECORD_SEPARATOR = "\n"
167
+ TOOL_NAME_WORD_BREAK_PATTERN = r"[_\-]+|(?<=[a-z0-9])(?=[A-Z])"
116
168
  PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
117
169
  TASK_LIST_NUDGE = (
118
170
  "The user follows your work in the task list. Give each ask an item in the session's task list"
119
- " tool and keep each item's status current as the work moves."
171
+ " tool and keep each item's status current as the work moves. Remove completed items before the"
172
+ " turn ends, so the list shows only open work."
120
173
  )
121
174
  TASK_LIST_NUDGE_ONCE_MARKER_NAME = "tracking_nudge"
@@ -0,0 +1,79 @@
1
+ """Constants for the wording that says something waits on the user."""
2
+
3
+ import re
4
+
5
+ WORD_START = r"(?<![^\W_])"
6
+ WORD_END = r"(?![^\W_])"
7
+ LINK_TARGET_LIMIT = 256
8
+ LINK_TARGET_SPAN = "{0," + str(LINK_TARGET_LIMIT) + "}"
9
+ LINK_CLOSER = (
10
+ r"\](?:\([^\s)]" + LINK_TARGET_SPAN + r"\)|\[[^\s\]]" + LINK_TARGET_SPAN + r"\])?"
11
+ )
12
+ PHRASE_GAP = r"[*_\[]{0,3}(?:" + LINK_CLOSER + r"[*_]{0,3})?\s+[*_\[]{0,3}"
13
+ PHRASE_GROUP = "phrase"
14
+ USER_STEP_PATTERN = re.compile(
15
+ WORD_START
16
+ + "(?=(?P<" + PHRASE_GROUP + ">"
17
+ + (
18
+ r"(?:needs?\s+your?"
19
+ r"|need(?:ed|s)?\s+from\s+you"
20
+ r"|wait(?:s|ing)?\s+(?:on|for)\s+your?"
21
+ r"|blocked\s+on\s+you"
22
+ r"|you(?:\s+still)?\s+need\s+to"
23
+ r"|you(?:['’]ll|\s+will)\s+need\s+to"
24
+ r"|for\s+you\s+to\s+(?:do|run|merge|approve|add|paste|click|decide|confirm|archive|sign|set)"
25
+ r"|(?:let\s+me\s+know|tell\s+me|say)\s+when"
26
+ r"|action\s+(?:needed|required))"
27
+ ).replace(r"\s+", PHRASE_GAP)
28
+ + WORD_END
29
+ + "))",
30
+ re.IGNORECASE,
31
+ )
32
+ CLAUSE_WORD_PATTERN = re.compile(r"(?<!\S)\S+")
33
+ WORD_RUN_PATTERN = re.compile(r"\S+")
34
+ EMPHASIS_MARKS = "*_"
35
+ MARKER_WORD_PATTERN = re.compile(r"[-+#>\d)(\[\]]*")
36
+ ALL_ABSENCE_WORDS = frozenset({"nothing", "none", "nobody"})
37
+ ALL_CLAUSE_OPENING_NEGATORS = frozenset({"no", "neither", "nor"})
38
+ THERE_WORD = "there"
39
+ ALL_THERE_VERBS = frozenset({"is", "are", "was", "were"})
40
+ ALL_LATE_NEGATORS = frozenset({"not", "never", "without"})
41
+ ALL_CONTRACTED_NEGATOR_ENDINGS = ("n't", "n’t")
42
+ ALL_NO_LONGER_WORDS = ("no", "longer")
43
+ MAXIMUM_WORDS_AFTER_LATE_NEGATOR = 3
44
+ NEGATED_TAIL_PATTERN = re.compile(
45
+ r"(?:[^\S\n]|[*_]){0,8}[:\-–—](?:[^\S\n]|[*_]){0,8}"
46
+ r"(?:none|nothing|n/a|no[^\S\n]+(?:action|step)s?)"
47
+ r"(?:[^\S\n]+(?:needed|required|for[^\S\n]+now|at[^\S\n]+this[^\S\n]+time|right[^\S\n]+now))?"
48
+ r"[*_]{0,3}[.!?]?[*_]{0,3}[^\S\n]*$",
49
+ re.IGNORECASE | re.MULTILINE,
50
+ )
51
+ CLAUSE_BREAK_PATTERN = re.compile(r"[.!?,;:|\n]|\b(?:and|but|so|then|while)\b", re.IGNORECASE)
52
+ LINE_BREAK = "\n"
53
+ LINE_ENDING_PATTERN = re.compile(r"\r\n?")
54
+ ODD_LINE_END_PATTERN = re.compile(r"[\x0b\x0c\x1c\x1d\x1e\x85\u2028\u2029]")
55
+ CODE_SPAN_STAND_IN = "\ufffc"
56
+ CODE_SPAN_SPACE = " "
57
+ HTML_LITERAL_STAND_IN_TEXT = "\ufffd"
58
+ CLAUSE_LEAD_WINDOW_CHARACTERS = 240
59
+ BARE_IMPERATIVE_PATTERN = re.compile(r"say\s", re.IGNORECASE)
60
+ OPENER_MARKER_CHARACTERS = "-+#>.)([]*_0123456789"
61
+ ALL_INSTRUCTION_OPENERS = frozenset({(), ("please",), ("just",), ("please", "just")})
62
+ ALL_HTML_HIDDEN_TAGS = frozenset(
63
+ {"script", "style", "template", "title", "textarea", "noscript", "code", "pre", "blockquote"}
64
+ )
65
+ ALL_HTML_INLINE_TAGS = frozenset(
66
+ {
67
+ "a", "abbr", "b", "bdi", "bdo", "big", "cite", "code", "data", "del", "dfn", "em", "font", "i", "img",
68
+ "ins", "kbd", "label", "mark", "q", "s", "samp", "small", "span", "strike", "strong", "sub", "sup",
69
+ "time", "tt", "u", "var", "wbr",
70
+ }
71
+ )
72
+ HTML_LINE_BREAK_TAG = "br"
73
+ HTML_SOURCE_SPACE_PATTERN = re.compile(r"[ \t\r\n\f]+")
74
+ HTML_SOURCE_SPACE = " "
75
+ HTML_BLOCK_SEPARATOR = "\n\n"
76
+ ALL_HTML_FILE_SUFFIXES = frozenset({".html", ".htm"})
77
+ ALL_SENT_TEXT_FILE_SUFFIXES = frozenset({".md", ".markdown", ".txt"}) | ALL_HTML_FILE_SUFFIXES
78
+ MAXIMUM_SENT_FILE_BYTES = 262144
79
+ BINARY_READ_MODE = "rb"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.117.1",
3
+ "version": "8.117.2",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -6,6 +6,6 @@ Ask one short question per item, never a chat list, with two or three choices, e
6
6
 
7
7
  Find the native question tool. Claude may use `AskUserQuestion`; Codex may use `request_user_input_async` or `request_user_input`. Honor mode rules. Put the question and choices in its fields. If unusable, ask in chat.
8
8
 
9
- When the user asks for option cards or a Codex visual comparison, read the full text first.
9
+ To hand over a step, option cards, or a Codex visual comparison, read the full text first.
10
10
 
11
11
  **Full text:** [`~/.claude/docs/rule-guides/question-presentation.md`](../docs/rule-guides/question-presentation.md).