claude-dev-env 8.117.0 → 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.
Files changed (39) hide show
  1. package/bin/ever-registered-hooks.test.mjs +4 -0
  2. package/docs/references/working-style.md +3 -0
  3. package/docs/rule-guides/question-presentation.md +8 -0
  4. package/hooks/blocking/final_reply_gate.py +20 -7
  5. package/hooks/blocking/open_tasks_stop_gate.py +133 -7
  6. package/hooks/blocking/open_tasks_transcript.py +77 -9
  7. package/hooks/blocking/test_final_reply_gate.py +14 -0
  8. package/hooks/blocking/test_open_tasks_stop_gate.py +204 -1
  9. package/hooks/blocking/test_open_tasks_transcript.py +123 -0
  10. package/hooks/blocking/test_turn_review_child.py +166 -0
  11. package/hooks/blocking/test_turn_review_claim.py +194 -0
  12. package/hooks/blocking/test_turn_review_repositories.py +65 -0
  13. package/hooks/blocking/test_turn_review_state.py +132 -0
  14. package/hooks/blocking/test_turn_review_transcript.py +125 -0
  15. package/hooks/blocking/test_user_step_wording.py +481 -0
  16. package/hooks/blocking/turn_review_child.py +145 -0
  17. package/hooks/blocking/turn_review_claim.py +306 -0
  18. package/hooks/blocking/turn_review_gate.py +32 -808
  19. package/hooks/blocking/turn_review_repositories.py +58 -0
  20. package/hooks/blocking/turn_review_state.py +260 -0
  21. package/hooks/blocking/turn_review_transcript.py +158 -0
  22. package/hooks/blocking/user_step_wording.py +384 -0
  23. package/hooks/features/conduct-gates.md +2 -2
  24. package/hooks/hooks_constants/final_reply_gate_constants.py +1 -1
  25. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +58 -5
  26. package/hooks/hooks_constants/session_title_constants.py +2 -2
  27. package/hooks/hooks_constants/user_step_wording_constants.py +79 -0
  28. package/hooks/routing/test_thread_spawn_pace_hook.py +32 -0
  29. package/hooks/session/test_background_silence_prompt.py +8 -0
  30. package/hooks/session/test_tracking_nudge.py +11 -0
  31. package/hooks/session_title_transcript.py +38 -17
  32. package/hooks/test_session_title_transcript.py +31 -0
  33. package/package.json +1 -1
  34. package/rules/question-presentation.md +1 -1
  35. package/scripts/account_broker_support.py +24 -5
  36. package/scripts/dev_env_scripts_constants/account_broker_constants.py +1 -0
  37. package/scripts/policy_lint/config/approved_test_pairs.py +27 -0
  38. package/scripts/test_account_broker_support.py +43 -1
  39. package/scripts/tests/test_policy_lint_rules_pairing.py +24 -0
@@ -20,6 +20,10 @@ test('EVER_REGISTERED_HOOK_RELATIVE_PATHS includes every script the package regi
20
20
  );
21
21
  });
22
22
 
23
+ test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the question brief gate', () => {
24
+ assert.ok(EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/question_brief_gate.py'));
25
+ });
26
+
23
27
  test('EVER_REGISTERED_HOOK_RELATIVE_PATHS keeps the retired merge-over-review card gate', () => {
24
28
  assert.equal(
25
29
  EVER_REGISTERED_HOOK_RELATIVE_PATHS.has('blocking/merge_over_review_offer_gate.py'),
@@ -6,6 +6,8 @@ The SessionStart hook `hooks/session/working_style_prompt.py` points every sessi
6
6
 
7
7
  - Document each task in a location that remains easy to find later.
8
8
  - Keep a running scratch text ledger as you work.
9
+ - Remove completed items from the task list before the turn ends, so the list shows only open work.
10
+ - Read an open item's live state before you show it to the user as open.
9
11
  - Keep each task list subject to 80 characters or fewer, start it with who acts (Me, You, or Handed off), and say what is left; put detail in the description.
10
12
 
11
13
  ## Presentation
@@ -39,3 +41,4 @@ The SessionStart hook `hooks/session/working_style_prompt.py` points every sessi
39
41
  - Ask one focused clarification question when the ambiguity changes the outcome, scope, audience, format, or risk.
40
42
  - Use a clearly stated low-risk assumption when the intended result remains stable.
41
43
  - Pause for the user's choice before making a high-impact decision.
44
+ - Hand the user a step as its own question, with the command block to paste or the link to open inside it. Leave long guides out.
@@ -6,6 +6,14 @@ Full text behind [`rules/question-presentation.md`](../../rules/question-present
6
6
 
7
7
  The user may see only the question dialog or the closing line of a reply. Each time a question stays open, send it through the question tool again, with the context inside the question text and each option's effect in its description. A closing line that repeats the question reaches the user with no brief. The `final_reply_gate.py` Stop hook blocks a reply whose last paragraph ends with a question mark, or says a question still stands, when the turn sent no question tool call.
8
8
 
9
+ ## A step that waits on the user
10
+
11
+ An item can close while it sits on a list. Before a reply or a sent file says something waits on the user, read the live state of each item it shows as open: the pull request, the session, the setting, or the log. Drop each one that is done. Send each step that still stands open as its own question through the question tool: one short sentence on what the step does, with the command block to paste or the link to open inside the question. Where the host has no question tool, give each step its own short paragraph with its block or link.
12
+
13
+ Remove completed items from the task list before the turn ends, so the list shows only open work.
14
+
15
+ The `open_tasks_stop_gate.py` Stop hook holds the turn once when completed items sit beside open ones on the session's own task list. It also holds the turn once when the closing reply, or a Markdown, text, or HTML file the turn sent, says something waits on the user and the turn ran no read call or sent no question tool call.
16
+
9
17
  ## Several items, one question at a time
10
18
 
11
19
  When the user has several items to review or decide, such as test cases, findings, or a plan's steps, do not post the list in chat and ask about it as a whole. Send the first item through the question tool with a short brief: its context and each choice's effect. Send the next item after the user answers. A long list in chat makes the user read everything at once, and the user asked for the items bit by bit.
@@ -79,8 +79,8 @@ def _unescaped_start(paragraph_text: str, run_start: int) -> int:
79
79
  return run_start + (run_start - backslash_start) % BACKSLASHES_PER_LITERAL
80
80
 
81
81
 
82
- def code_spans_masked(paragraph_text: str) -> str:
83
- """Return the paragraph with one space where each code span sat.
82
+ def code_spans_masked(paragraph_text: str, masked_code_text: str = MASKED_CODE_TEXT) -> str:
83
+ """Return the paragraph with one space, or the given text, where each code span sat.
84
84
 
85
85
  A backtick run opens a span unless an odd run of backslashes escapes its
86
86
  first backtick. The span closes at the next run of the same length::
@@ -104,7 +104,7 @@ def code_spans_masked(paragraph_text: str) -> str:
104
104
  run_index += 1
105
105
  continue
106
106
  closer_index = same_length_indexes[closer_position]
107
- all_masked_pieces.extend((paragraph_text[copied_up_to:opener_start], MASKED_CODE_TEXT))
107
+ all_masked_pieces.extend((paragraph_text[copied_up_to:opener_start], masked_code_text))
108
108
  copied_up_to = all_runs[closer_index][1]
109
109
  run_index = closer_index + 1
110
110
  all_masked_pieces.append(paragraph_text[copied_up_to:])
@@ -214,17 +214,30 @@ def windows_path_violation(reply_text: str) -> str | None:
214
214
  return None
215
215
 
216
216
 
217
- def closing_paragraph(reply_text: str) -> str:
218
- """Return the last prose paragraph, with fences, HTML blocks, quoted paragraphs, and code spans left out."""
217
+ def prose_paragraphs(reply_text: str) -> list[str]:
218
+ """Return each prose paragraph, with fences, HTML blocks, quoted paragraphs, and code spans left out."""
219
+ return prose_paragraphs_with_code_as(reply_text, MASKED_CODE_TEXT)
220
+
221
+
222
+ def prose_paragraphs_with_code_as(reply_text: str, masked_code_text: str) -> list[str]:
223
+ """Return each prose paragraph, with the given text where each code span sat.
224
+
225
+ Fences, HTML blocks, and quoted paragraphs are left out.
226
+ """
219
227
  line_feed_text = reply_text.replace(CARRIAGE_RETURN_LINE_BREAK, LINE_BREAK)
220
228
  unfenced_text = blocks_masked(line_feed_text, FENCE_OPENER_PATTERN, _fence_closer_for)
221
229
  unfenced_text = blocks_masked(unfenced_text, HTML_BLOCK_OPENER_PATTERN, _html_block_closer_for)
222
230
  unquoted_text = QUOTED_LINE_PATTERN.sub("", unfenced_text)
223
- all_prose_paragraphs = [
224
- code_spans_masked(each_paragraph).strip()
231
+ return [
232
+ code_spans_masked(each_paragraph, masked_code_text).strip()
225
233
  for each_paragraph in BLOCK_BOUNDARY_PATTERN.split(unquoted_text)
226
234
  if each_paragraph.strip()
227
235
  ]
236
+
237
+
238
+ def closing_paragraph(reply_text: str) -> str:
239
+ """Return the last prose paragraph, with fences, HTML blocks, quoted paragraphs, and code spans left out."""
240
+ all_prose_paragraphs = prose_paragraphs(reply_text)
228
241
  return all_prose_paragraphs[-1] if all_prose_paragraphs else ""
229
242
 
230
243
 
@@ -23,9 +23,36 @@ The gate holds the turn once when all three hold::
23
23
  allow: "Export the APKs" -> reply only -> stop
24
24
  allow: "Export the APKs" -> AskUserQuestion -> stop
25
25
 
26
- The reply text is never checked. One tracker call releases the turn, and a
27
- turn the gate already held ends on the next stop, so the gate costs at most one
28
- extra step per turn.
26
+ The user reads the task list to see what is open, so the gate also holds the
27
+ turn once when completed items sit beside open ones::
28
+
29
+ block: 27 completed, 13 pending -> stop
30
+ allow: 3 completed, none open -> stop
31
+ allow: 13 pending -> stop
32
+
33
+ The list is the session's task store, or the transcript's list when the session
34
+ has no store. A list that ``CLAUDE_CODE_TASK_LIST_ID`` shares with other
35
+ sessions is left alone.
36
+
37
+ A turn that tells the user something waits on them reads the live state first
38
+ and hands over each step through the question tool. The gate reads the closing
39
+ reply and each Markdown, text, or HTML file the turn sent with SendUserFile, as
40
+ ``user_step_wording.py`` describes, and holds the turn once::
41
+
42
+ block: "Three items need you." no read call this turn
43
+ block: "Three items need you." no question tool call this turn
44
+ allow: the same reply after a read call and an AskUserQuestion call
45
+ allow: "Both builds passed."
46
+ allow: any reply when the transcript cannot be read
47
+
48
+ A read call is a shell, a file or web read, a subagent, or a tool whose name
49
+ carries a read word, as ``open_tasks_transcript.is_read_tool_name`` lists. The
50
+ gate checks that a read ran, and leaves which item it read to the agent. Each
51
+ such hold tells the agent to read the live state of every item it shows as
52
+ open, and to end the turn when the wording hands the user no step.
53
+
54
+ One reason carries every finding. A turn the gate already held ends on the next
55
+ stop, so the gate costs at most one extra step per turn.
29
56
 
30
57
  A hold exits with code 2 and writes the reason to stdout and stderr. Claude
31
58
  Code marks a held stop with ``stop_hook_active``. Codex turns the reason into
@@ -49,20 +76,27 @@ blocking_directory = str(Path(__file__).resolve().parent)
49
76
  if blocking_directory not in sys.path:
50
77
  sys.path.insert(0, blocking_directory)
51
78
 
79
+ from hooks_constants.final_reply_gate_constants import LAST_ASSISTANT_MESSAGE_KEY
52
80
  from hooks_constants.hook_block_logger import log_hook_block
53
81
  from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
54
82
  from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
83
+ from hooks_constants.once_per_session_constants import SESSION_ID_KEY
55
84
  from hooks_constants.stop_hook_hold import hold_stop
56
85
  from open_task_asks import claude_home, is_ask
57
86
  from open_tasks_transcript import TaskItem, TranscriptReplay, normalized_text, parsed_object, replayed_transcript
87
+ from user_step_wording import file_waiting_phrase, waiting_phrase
58
88
  from hooks_constants.open_tasks_stop_gate_constants import (
59
89
  ALLOW_EXIT_CODE,
60
- BLOCK_REASON,
90
+ COMPLETED_ITEMS_REASON_TEMPLATE,
91
+ COMPLETED_STATUS,
61
92
  CURSOR_COMPLETED_STATUS,
62
93
  CURSOR_CONVERSATION_ID_KEY,
63
94
  CURSOR_LOOP_COUNT_KEY,
64
95
  CURSOR_STATUS_KEY,
65
96
  HOOK_EVENT_NAME,
97
+ INCOMPLETE_STATUSES,
98
+ KEEP_REPLY_INSTRUCTION,
99
+ NO_STEP_INSTRUCTION,
66
100
  STOP_HOOK_ACTIVE_KEY,
67
101
  TASK_FILE_GLOB,
68
102
  TASK_ID_KEY,
@@ -72,7 +106,13 @@ from hooks_constants.open_tasks_stop_gate_constants import (
72
106
  TASK_SUBJECT_KEY,
73
107
  TASKS_DIRECTORY_NAME,
74
108
  TRANSCRIPT_PATH_KEY,
109
+ UNASKED_STEP_REASON,
110
+ UNREAD_STEP_REASON,
111
+ UNTRACKED_WORK_REASON,
112
+ USER_STEP_LEAD_TEMPLATE,
75
113
  UTF8_ENCODING,
114
+ WORD_SEPARATOR,
115
+ WORKING_DIRECTORY_KEY,
76
116
  )
77
117
 
78
118
 
@@ -131,6 +171,91 @@ def is_untracked_work_turn(replay: TranscriptReplay) -> bool:
131
171
  return replay.has_turn_work_tool and not replay.has_turn_tracker_write and is_ask(replay.turn_prompt_text)
132
172
 
133
173
 
174
+ def shown_task_items(session_id: object, replay: TranscriptReplay) -> list[TaskItem]:
175
+ """Return the task list the user sees: the task store when the session has one, else the transcript's list."""
176
+ all_store_items = task_store_items(session_id)
177
+ return all_store_items if all_store_items is not None else replay.items() or []
178
+
179
+
180
+ def stale_list_reason(all_items: list[TaskItem]) -> str | None:
181
+ """Return the reason for completed items that sit beside open ones, or None.
182
+
183
+ ::
184
+
185
+ 27 completed, 13 pending -> reason naming 27 of 40 items
186
+ 3 completed, none open -> None
187
+ 2 pending -> None
188
+ """
189
+ completed_count = sum(each_item.status == COMPLETED_STATUS for each_item in all_items)
190
+ open_count = sum(each_item.status in INCOMPLETE_STATUSES for each_item in all_items)
191
+ if not completed_count or not open_count:
192
+ return None
193
+ return COMPLETED_ITEMS_REASON_TEMPLATE.format(
194
+ completed_count=completed_count, item_count=completed_count + open_count
195
+ )
196
+
197
+
198
+ def turn_waiting_phrase(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> str | None:
199
+ """Return the first phrase the closing reply or a sent text file uses to say something waits on the user; a path sent twice is read once."""
200
+ reply_text = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
201
+ reply_phrase = waiting_phrase(reply_text) if isinstance(reply_text, str) else None
202
+ if reply_phrase is not None:
203
+ return reply_phrase
204
+ working_directory = all_hook_input_fields.get(WORKING_DIRECTORY_KEY)
205
+ all_file_phrases = (
206
+ file_waiting_phrase(each_path, working_directory) for each_path in dict.fromkeys(replay.turn_sent_file_paths)
207
+ )
208
+ return next((each_phrase for each_phrase in all_file_phrases if each_phrase is not None), None)
209
+
210
+
211
+ def user_step_reasons(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> list[str]:
212
+ """Return a reason for each thing a turn skipped before it told the user something waits on them.
213
+
214
+ ::
215
+
216
+ "Three items need you.", no read call -> the live read reason
217
+ "Three items need you.", no question tool call -> the question tool reason
218
+ the same reply after both calls -> []
219
+ "Both builds passed." -> []
220
+
221
+ A session whose transcript cannot be read gives no reason.
222
+ """
223
+ transcript_path = all_hook_input_fields.get(TRANSCRIPT_PATH_KEY)
224
+ if not isinstance(transcript_path, str) or not Path(transcript_path).is_file():
225
+ return []
226
+ all_reasons = [
227
+ each_reason
228
+ for each_reason, has_turn_call in (
229
+ (UNREAD_STEP_REASON, replay.has_turn_read_tool),
230
+ (UNASKED_STEP_REASON, replay.has_turn_question_tool),
231
+ )
232
+ if not has_turn_call
233
+ ]
234
+ if not all_reasons:
235
+ return []
236
+ phrase = turn_waiting_phrase(all_hook_input_fields, replay)
237
+ return [] if phrase is None else [USER_STEP_LEAD_TEMPLATE.format(phrase=phrase), *all_reasons]
238
+
239
+
240
+ def tracker_reasons(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> list[str]:
241
+ """Return a reason for untracked work, and one for completed items beside open ones on the session's own list."""
242
+ all_reasons = [UNTRACKED_WORK_REASON] if is_untracked_work_turn(replay) else []
243
+ if os.environ.get(TASK_LIST_ID_ENVIRONMENT_VARIABLE):
244
+ return all_reasons
245
+ stale_reason = stale_list_reason(shown_task_items(all_hook_input_fields.get(SESSION_ID_KEY), replay))
246
+ return all_reasons if stale_reason is None else [*all_reasons, stale_reason]
247
+
248
+
249
+ def turn_block_reason(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> str | None:
250
+ """Return one reason that carries every finding on the turn, or None when the turn may end."""
251
+ all_tracker_reasons = tracker_reasons(all_hook_input_fields, replay)
252
+ all_step_reasons = user_step_reasons(all_hook_input_fields, replay)
253
+ if not all_tracker_reasons and not all_step_reasons:
254
+ return None
255
+ all_closing_lines = [NO_STEP_INSTRUCTION] if all_step_reasons else [KEEP_REPLY_INSTRUCTION]
256
+ return WORD_SEPARATOR.join([*all_tracker_reasons, *all_step_reasons, *all_closing_lines])
257
+
258
+
134
259
  def is_held_stop(all_hook_input_fields: dict[str, object]) -> bool:
135
260
  """Return True when a stop hook already held this turn once, or the Cursor run did not complete."""
136
261
  if all_hook_input_fields.get(STOP_HOOK_ACTIVE_KEY) is True:
@@ -147,10 +272,11 @@ def main() -> int:
147
272
  hook_input = read_hook_input_dictionary_from_stdin()
148
273
  if hook_input is None or is_held_stop(hook_input):
149
274
  return ALLOW_EXIT_CODE
150
- if not is_untracked_work_turn(replayed_transcript(hook_input.get(TRANSCRIPT_PATH_KEY))):
275
+ block_reason = turn_block_reason(hook_input, replayed_transcript(hook_input.get(TRANSCRIPT_PATH_KEY)))
276
+ if block_reason is None:
151
277
  return ALLOW_EXIT_CODE
152
- log_hook_block(Path(__file__).name, HOOK_EVENT_NAME, BLOCK_REASON)
153
- return hold_stop(hook_input, BLOCK_REASON)
278
+ log_hook_block(Path(__file__).name, HOOK_EVENT_NAME, block_reason)
279
+ return hold_stop(hook_input, block_reason)
154
280
 
155
281
 
156
282
  if __name__ == "__main__":
@@ -26,6 +26,11 @@ The replay also notes what the current turn did::
26
26
  TaskList, TaskGet, and the Codex request_user_input card
27
27
  has_turn_question_tool an AskUserQuestion, hearthbot decision card, or Codex
28
28
  request_user_input call ran
29
+ has_turn_read_tool a call ran that can read state: a shell, a file or web
30
+ read, a subagent, or a tool whose name carries a read
31
+ word such as ``get``, ``list`` or ``read`` and no
32
+ write word such as ``update``
33
+ turn_sent_file_paths the paths the turn's SendUserFile calls sent
29
34
 
30
35
  A turn starts at the last user prompt record. A tool result, a record flagged
31
36
  ``isMeta``, ``isSidechain`` or ``isCompactSummary``, and a ``Stop hook feedback``
@@ -49,6 +54,7 @@ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
49
54
  if hooks_root_directory not in sys.path:
50
55
  sys.path.insert(0, hooks_root_directory)
51
56
 
57
+ from hooks_constants.send_user_file_worktree_root_gate_constants import SEND_USER_FILE_TOOL_NAME
52
58
  from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
53
59
  from hooks_constants.open_tasks_stop_gate_constants import (
54
60
  ALL_SKIPPED_PROMPT_FLAGS,
@@ -56,7 +62,10 @@ from hooks_constants.open_tasks_stop_gate_constants import (
56
62
  ALL_CODEX_TOOL_CALL_TYPES,
57
63
  ALL_NON_WORK_TOOL_NAMES,
58
64
  ALL_QUESTION_TOOL_NAMES,
65
+ ALL_READ_TOOL_NAMES,
66
+ ALL_READ_WORDS,
59
67
  ALL_TRACKER_TOOL_NAMES,
68
+ ALL_WRITE_WORDS,
60
69
  ASSISTANT_ROLE,
61
70
  CCD_PLAN_ADVANCE_KEY,
62
71
  CCD_PLAN_CONTENT_KEY,
@@ -67,6 +76,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
67
76
  CCD_PLAN_TOOL_NAME,
68
77
  CODEX_ARGUMENTS_KEY,
69
78
  CODEX_FUNCTION_CALL_TYPE,
79
+ CODEX_LOCAL_SHELL_CALL_TYPE,
70
80
  CODEX_MESSAGE_TYPE,
71
81
  CODEX_PAYLOAD_KEY,
72
82
  CODEX_PLAN_KEY,
@@ -86,6 +96,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
86
96
  PENDING_STATUS,
87
97
  RECORD_TYPE_KEY,
88
98
  ROLE_KEY,
99
+ SENT_FILES_KEY,
89
100
  STOP_HOOK_FEEDBACK_PREFIX,
90
101
  TASK_CREATED_PATTERN,
91
102
  TASK_CREATE_TOOL_NAME,
@@ -102,6 +113,9 @@ from hooks_constants.open_tasks_stop_gate_constants import (
102
113
  TODO_MERGE_KEY,
103
114
  TODO_WRITE_TOOL_NAME,
104
115
  TOOL_INPUT_KEY,
116
+ RECORD_SEPARATOR,
117
+ TOOL_NAME_SERVER_SEPARATOR,
118
+ TOOL_NAME_WORD_BREAK_PATTERN,
105
119
  TOOL_NAME_KEY,
106
120
  TOOL_RESULT_BLOCK_TYPE,
107
121
  TOOL_USE_BLOCK_TYPE,
@@ -133,10 +147,13 @@ def normalized_text(text: str) -> str:
133
147
 
134
148
 
135
149
  def parsed_object(json_text: str) -> dict[str, object] | None:
136
- """Return the JSON object in the text, or None for anything else."""
150
+ """Return the JSON object in the text, or None for anything else.
151
+
152
+ Text that is no JSON, or JSON nested too deep to parse, is None.
153
+ """
137
154
  try:
138
155
  parsed_value = json.loads(json_text)
139
- except ValueError:
156
+ except (ValueError, RecursionError):
140
157
  return None
141
158
  return parsed_value if isinstance(parsed_value, dict) else None
142
159
 
@@ -145,14 +162,10 @@ def _transcript_records(transcript_path: object) -> list[dict[str, object]]:
145
162
  if not isinstance(transcript_path, str):
146
163
  return []
147
164
  try:
148
- all_lines = (
149
- Path(transcript_path)
150
- .read_text(encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
151
- .splitlines()
152
- )
153
- except OSError:
165
+ transcript_text = Path(transcript_path).read_text(encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
166
+ except (OSError, ValueError):
154
167
  return []
155
- all_records = (parsed_object(each_line) for each_line in all_lines)
168
+ all_records = (parsed_object(each_line) for each_line in transcript_text.split(RECORD_SEPARATOR))
156
169
  return [each_record for each_record in all_records if each_record is not None]
157
170
 
158
171
 
@@ -232,6 +245,16 @@ def is_codex_work_call(all_record_fields: dict[str, object]) -> bool:
232
245
  return tool_name != CODEX_PLAN_TOOL_NAME and is_work_tool_name(tool_name)
233
246
 
234
247
 
248
+ def is_codex_read_call(all_record_fields: dict[str, object]) -> bool:
249
+ """Return True for a Codex tool call record whose tool can read state; a ``local_shell_call`` carries no name and counts."""
250
+ payload_body = _codex_payload(all_record_fields)
251
+ if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
252
+ return False
253
+ if payload_body.get(RECORD_TYPE_KEY) == CODEX_LOCAL_SHELL_CALL_TYPE:
254
+ return True
255
+ return is_read_tool_name(payload_body.get(TOOL_NAME_KEY))
256
+
257
+
235
258
  def is_codex_question_call(all_record_fields: dict[str, object]) -> bool:
236
259
  """Return True for a Codex tool call record that sends a question card."""
237
260
  payload_body = _codex_payload(all_record_fields)
@@ -248,6 +271,43 @@ def is_work_tool_name(tool_name: object) -> bool:
248
271
  )
249
272
 
250
273
 
274
+ def is_read_tool_name(tool_name: object) -> bool:
275
+ """Return True for a tool that can read state.
276
+
277
+ ::
278
+
279
+ Bash, Read, WebFetch, Agent, shell -> True
280
+ mcp__github__pull_request_read -> True
281
+ mcp__claude-code-remote__get_session -> True
282
+ ReadMcpResourceTool, mcp__x__getIssue -> True
283
+ Write, SendUserFile, TaskUpdate -> False
284
+ TaskList, TaskGet -> False
285
+ mcp__tracker__update_status, AppendLog -> False
286
+ mcp__logs__write_entry -> False
287
+
288
+ A name counts when one of its words is a read word and none is a write
289
+ word. Only the part after the last double underscore is read, so a server
290
+ name never decides it. Words are split at underscores, hyphens, and a
291
+ capital that follows a lower-case letter or a digit. A tool that is no work tool never counts: TaskList and TaskGet read
292
+ the task list itself, and ToolSearch and the question tools read no state.
293
+ """
294
+ if not isinstance(tool_name, str) or tool_name in ALL_NON_WORK_TOOL_NAMES:
295
+ return False
296
+ if tool_name in ALL_READ_TOOL_NAMES:
297
+ return True
298
+ action_name = tool_name.rsplit(TOOL_NAME_SERVER_SEPARATOR, 1)[-1]
299
+ all_name_words = {each_word.lower() for each_word in re.split(TOOL_NAME_WORD_BREAK_PATTERN, action_name)}
300
+ return not ALL_READ_WORDS.isdisjoint(all_name_words) and ALL_WRITE_WORDS.isdisjoint(all_name_words)
301
+
302
+
303
+ def send_call_file_paths(tool_name: str, all_input_fields: dict[str, object]) -> list[str]:
304
+ """Return the file paths a SendUserFile call sends, or an empty list for any other call."""
305
+ all_sent_files = all_input_fields.get(SENT_FILES_KEY)
306
+ if tool_name != SEND_USER_FILE_TOOL_NAME or not isinstance(all_sent_files, list):
307
+ return []
308
+ return [each_path for each_path in all_sent_files if isinstance(each_path, str)]
309
+
310
+
251
311
  def is_assistant_record(all_record_fields: dict[str, object]) -> bool:
252
312
  """Return True for a record the assistant wrote, by its type, its role, or its message role."""
253
313
  message_body = all_record_fields.get(MESSAGE_KEY)
@@ -349,12 +409,16 @@ class TranscriptReplay:
349
409
  self.has_turn_tracker_write = False
350
410
  self.has_turn_work_tool = False
351
411
  self.has_turn_question_tool = False
412
+ self.has_turn_read_tool = False
413
+ self.turn_sent_file_paths: list[str] = []
352
414
 
353
415
  def start_turn(self, prompt_text: str) -> None:
354
416
  self.turn_prompt_text = prompt_text
355
417
  self.has_turn_tracker_write = False
356
418
  self.has_turn_work_tool = False
357
419
  self.has_turn_question_tool = False
420
+ self.has_turn_read_tool = False
421
+ self.turn_sent_file_paths = []
358
422
 
359
423
  def apply_record(self, all_record_fields: dict[str, object]) -> None:
360
424
  prompt_text = codex_prompt_text(all_record_fields)
@@ -373,6 +437,7 @@ class TranscriptReplay:
373
437
  return
374
438
  if is_codex_work_call(all_record_fields):
375
439
  self.has_turn_work_tool = True
440
+ self.has_turn_read_tool = self.has_turn_read_tool or is_codex_read_call(all_record_fields)
376
441
  return
377
442
  is_typed_assistant_record = all_record_fields.get(RECORD_TYPE_KEY) == ASSISTANT_RECORD_TYPE
378
443
  is_from_assistant = is_assistant_record(all_record_fields)
@@ -423,12 +488,15 @@ class TranscriptReplay:
423
488
  self.apply_tool_use(tool_name, str(all_block_fields.get(TASK_ID_KEY)), all_tool_arguments)
424
489
  if is_from_assistant:
425
490
  self.note_turn_tool(tool_name)
491
+ self.turn_sent_file_paths.extend(send_call_file_paths(tool_name, all_tool_arguments))
426
492
  elif block_type == TOOL_RESULT_BLOCK_TYPE:
427
493
  self.apply_tool_result(all_block_fields)
428
494
 
429
495
  def note_turn_tool(self, tool_name: str) -> None:
430
496
  if tool_name in ALL_QUESTION_TOOL_NAMES:
431
497
  self.has_turn_question_tool = True
498
+ if is_read_tool_name(tool_name):
499
+ self.has_turn_read_tool = True
432
500
  if tool_name in ALL_TRACKER_TOOL_NAMES:
433
501
  self.has_turn_tracker_write = True
434
502
  elif is_work_tool_name(tool_name):
@@ -347,6 +347,20 @@ def test_should_pass_a_closing_question_when_the_transcript_cannot_be_read(
347
347
  assert stdout_text == ""
348
348
 
349
349
 
350
+ def test_should_list_each_prose_paragraph_without_fences_quotes_or_code_spans() -> None:
351
+ reply_text = "Both builds passed.\n\n```\nmake test\n```\n\n> Keep it or revert it?\n\nThe flag is `--fast`."
352
+ assert final_reply_gate.prose_paragraphs(reply_text) == ["Both builds passed.", "The flag is ."]
353
+ assert final_reply_gate.closing_paragraph(reply_text) == "The flag is ."
354
+
355
+
356
+ def test_should_put_the_given_text_in_place_of_each_code_span() -> None:
357
+ assert final_reply_gate.code_spans_masked("Not`-`e and `x`", masked_code_text="\ufffc") == "Not\ufffce and \ufffc"
358
+ assert final_reply_gate.prose_paragraphs_with_code_as("Not`-`e\n\nThe flag is `x`.", "\ufffc") == [
359
+ "Not\ufffce",
360
+ "The flag is \ufffc.",
361
+ ]
362
+
363
+
350
364
  def test_should_block_a_closing_question_when_the_transcript_holds_an_undecodable_byte(
351
365
  monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
352
366
  ) -> None: