claude-dev-env 8.123.0 → 8.125.0

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 (46) hide show
  1. package/bin/ever-registered-hooks.mjs +2 -0
  2. package/bin/ever-registered-hooks.test.mjs +5 -0
  3. package/bin/profile-stop-gate.mjs +5 -7
  4. package/bin/profile-stop-gate.test.mjs +29 -1
  5. package/docs/agents-guidance/asks.md +1 -1
  6. package/docs/rule-guides/question-presentation.md +1 -1
  7. package/docs/templates/artifact-page/README.md +14 -1
  8. package/docs/templates/artifact-page/review-rounds.md +1 -1
  9. package/docs/templates/artifact-page/template.html +26 -18
  10. package/docs/templates/html-plan/README.md +4 -0
  11. package/hooks/blocking/artifact_current_page_fixtures/piled_review_page.html +399 -0
  12. package/hooks/blocking/artifact_current_page_fixtures/rebuilt_review_page.html +403 -0
  13. package/hooks/blocking/artifact_current_page_gate.py +418 -0
  14. package/hooks/blocking/artifact_repeated_item_render.cjs +112 -0
  15. package/hooks/blocking/closing_reply_judge.py +332 -0
  16. package/hooks/blocking/closing_reply_shapes.py +365 -0
  17. package/hooks/blocking/conftest.py +84 -0
  18. package/hooks/blocking/open_tasks_stop_gate.py +259 -11
  19. package/hooks/blocking/open_tasks_transcript.py +55 -2
  20. package/hooks/blocking/open_tasks_transcript_records.py +67 -1
  21. package/hooks/blocking/question_brief_gate.py +6 -4
  22. package/hooks/blocking/test_artifact_current_page_gate.py +415 -0
  23. package/hooks/blocking/test_closing_reply_judge.py +246 -0
  24. package/hooks/blocking/test_closing_reply_shapes.py +247 -0
  25. package/hooks/blocking/test_open_tasks_stop_gate.py +626 -0
  26. package/hooks/blocking/test_open_tasks_transcript.py +57 -0
  27. package/hooks/blocking/test_open_tasks_transcript_records.py +48 -0
  28. package/hooks/blocking/test_question_brief_gate.py +22 -0
  29. package/hooks/features/conduct-gates.md +10 -3
  30. package/hooks/hooks.json +16 -1
  31. package/hooks/hooks_constants/artifact_current_page_gate_constants.py +91 -0
  32. package/hooks/hooks_constants/artifact_dark_mode_gate_constants.py +3 -3
  33. package/hooks/hooks_constants/closing_reply_judge_constants.py +143 -0
  34. package/hooks/hooks_constants/open_tasks_stop_gate_constants.py +101 -0
  35. package/hooks/hooks_constants/test_artifact_current_page_gate_constants.py +53 -0
  36. package/hooks/hooks_constants/test_artifact_dark_mode_gate_constants.py +6 -0
  37. package/hooks/hooks_constants/test_hook_time_budget.py +7 -0
  38. package/hooks/once_per_session.py +65 -1
  39. package/hooks/session/artifact_link_record.py +109 -0
  40. package/hooks/session/test_artifact_link_record.py +101 -0
  41. package/hooks/test_context_budget_hooks.py +2 -0
  42. package/hooks/test_once_per_session.py +35 -0
  43. package/package.json +1 -1
  44. package/scripts/policy_lint/adapter_configuration.py +6 -0
  45. package/scripts/policy_lint/config/constants.py +1 -0
  46. package/scripts/tests/test_adapter_configuration.py +8 -0
@@ -90,3 +90,87 @@ def multi_edit_payload() -> Callable[[str, list[dict[str, str]]], str]:
90
90
  )
91
91
 
92
92
  return _multi_edit_payload
93
+
94
+
95
+ UNPINNED_WHICH = shutil.which
96
+ STUB_SCRIPT_TEMPLATE = """#!{python}
97
+ import json, os, pathlib, sys, time
98
+ state = pathlib.Path(os.environ["JUDGE_STUB_STATE"])
99
+ record = {{
100
+ "argv": sys.argv[1:],
101
+ "stdin": sys.stdin.read(),
102
+ "cwd_entries": os.listdir(os.getcwd()),
103
+ "review_child": os.environ.get("CLAUDE_TURN_REVIEW_CHILD"),
104
+ "disable_claude_mds": os.environ.get("CLAUDE_CODE_DISABLE_CLAUDE_MDS"),
105
+ "disable_auto_memory": os.environ.get("CLAUDE_CODE_DISABLE_AUTO_MEMORY"),
106
+ "parent_session_id": os.environ.get("CLAUDE_CODE_SESSION_ID"),
107
+ }}
108
+ with (state / "calls.jsonl").open("a") as calls:
109
+ calls.write(json.dumps(record) + "\\n")
110
+ time.sleep(float((state / "sleep.txt").read_text()))
111
+ sys.stdout.write((state / "answer.txt").read_text())
112
+ sys.exit(int((state / "exit.txt").read_text()))
113
+ """
114
+
115
+
116
+ class JudgeStub:
117
+ """The state folder a stub ``claude`` reads its answer from and writes its calls to."""
118
+
119
+ def __init__(self, state_folder: Path) -> None:
120
+ self.state_folder = state_folder
121
+ self.answer(
122
+ verdict={
123
+ "promised_report": False,
124
+ "promise_span": "",
125
+ "decisions_as_list": False,
126
+ "list_span": "",
127
+ }
128
+ )
129
+ (state_folder / "sleep.txt").write_text("0")
130
+ (state_folder / "exit.txt").write_text("0")
131
+
132
+ def answer(
133
+ self,
134
+ verdict: dict[str, object] | None = None,
135
+ result: str | None = None,
136
+ **all_outer_fields: object,
137
+ ) -> None:
138
+ result_text = result if result is not None else json.dumps(verdict)
139
+ outer_answer = {
140
+ "type": "result",
141
+ "is_error": False,
142
+ "result": result_text,
143
+ **all_outer_fields,
144
+ }
145
+ (self.state_folder / "answer.txt").write_text(json.dumps(outer_answer))
146
+
147
+ def raw_stdout(self, stdout_text: str) -> None:
148
+ (self.state_folder / "answer.txt").write_text(stdout_text)
149
+
150
+ def sleep(self, seconds: float) -> None:
151
+ (self.state_folder / "sleep.txt").write_text(str(seconds))
152
+
153
+ def exit_code(self, code: int) -> None:
154
+ (self.state_folder / "exit.txt").write_text(str(code))
155
+
156
+ def calls(self) -> list[dict[str, object]]:
157
+ calls_path = self.state_folder / "calls.jsonl"
158
+ if not calls_path.is_file():
159
+ return []
160
+ return [json.loads(each_line) for each_line in calls_path.read_text().splitlines()]
161
+
162
+
163
+ @pytest.fixture
164
+ def judge_stub(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> JudgeStub:
165
+ """Put a stub ``claude`` first on PATH that records each call and prints the answer the test sets."""
166
+ executable_folder = tmp_path / "bin"
167
+ executable_folder.mkdir()
168
+ stub_path = executable_folder / "claude"
169
+ stub_path.write_text(STUB_SCRIPT_TEMPLATE.format(python=sys.executable))
170
+ stub_path.chmod(0o755)
171
+ state_folder = tmp_path / "state"
172
+ state_folder.mkdir()
173
+ monkeypatch.setenv("PATH", str(executable_folder))
174
+ monkeypatch.setattr(shutil, "which", UNPINNED_WHICH)
175
+ monkeypatch.setenv("JUDGE_STUB_STATE", str(state_folder))
176
+ return JudgeStub(state_folder)
@@ -23,6 +23,15 @@ 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
+ A Claude Code session that has no tracker tool cannot act on that hold, so the
27
+ gate passes the turn when the transcript shows the session's tool lists and no
28
+ tracker in them::
29
+
30
+ allow: prompt_snapshot tools and deferred_tools_delta name no tracker,
31
+ and no deferred_tools_record or call names one
32
+ block: a deferred_tools_delta lists TaskCreate, even when not yet loaded
33
+ block: no prompt_snapshot tools list or no deferred_tools_delta (Codex, Cursor)
34
+
26
35
  The user reads the task list to see what is open, so the gate also holds the
27
36
  turn once when completed items sit beside open ones::
28
37
 
@@ -51,8 +60,40 @@ gate checks that a read ran, and leaves which item it read to the agent. Each
51
60
  such hold tells the agent to read the live state of every item it shows as
52
61
  open, and to end the turn when the wording hands the user no step.
53
62
 
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.
63
+ The closing reply also gets two checks of its own: a promised later report,
64
+ and open items sent as a list. On a Claude Code stop with ``claude`` on PATH,
65
+ one model call in ``closing_reply_judge.py`` reads the reply; Codex and Cursor
66
+ stops, and a host with no ``claude``, use the phrase checks that
67
+ ``closing_reply_shapes.py`` describes. A judge that times out or gives no
68
+ usable verdict lets the stop go ahead. A stop inside a judge or review child
69
+ (``CLAUDE_TURN_REVIEW_CHILD=1``) goes ahead at once. The gate holds the turn
70
+ once::
71
+
72
+ block: "The benchmark table will be posted when you get back." no typed prompt asked for a report
73
+ block: "What I deferred:" over 3 or more items no question tool call this turn
74
+ allow: the same list after an AskUserQuestion call
75
+ allow: the same promise after the prompt "report back when the run ends"
76
+ allow: any reply when the transcript cannot be read
77
+
78
+ Such a hold names what it found and the steps, then one line that ends the
79
+ turn, then when the reply may stay as it is::
80
+
81
+ promise only -> "Then send the reworked reply and end the turn. Leave the promise as it is only when ..."
82
+ list present -> "Then send a short reply that names what you did and end the turn. Leave the list as it is only when ..."
83
+
84
+ One reason carries every finding. A Claude Code stop that a Stop hook already
85
+ held (``stop_hook_active``) gets only the closing-reply checks, and those hold
86
+ at most once per turn::
87
+
88
+ block: another hook held, then "I'll report back once CI ends." first such stop this turn
89
+ allow: the same stop again the turn's marker exists
90
+ allow: a stop after this gate held the turn its feedback sits in the turn
91
+ allow: a Codex turn, a prompt record with no ``uuid``, or a marker that cannot be kept
92
+
93
+ The marker is a file in the temp folder named for the session and the ``uuid``
94
+ of the prompt record that started the turn. A hold on the first stop writes it
95
+ too, so the gate costs at most one extra step per turn. The judge runs only
96
+ while the turn has no marker, so a stop after the hold makes no second call.
56
97
 
57
98
  A hold exits with code 2 and writes the reason to stdout and stderr. Claude
58
99
  Code marks a held stop with ``stop_hook_active``. Codex turns the reason into
@@ -68,6 +109,7 @@ from __future__ import annotations
68
109
  import os
69
110
  import sys
70
111
  from pathlib import Path
112
+ from typing import NamedTuple
71
113
 
72
114
  hooks_root_directory = str(Path(__file__).resolve().parent.parent)
73
115
  if hooks_root_directory not in sys.path:
@@ -82,11 +124,24 @@ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_s
82
124
  from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
83
125
  from hooks_constants.once_per_session_constants import SESSION_ID_KEY
84
126
  from hooks_constants.stop_hook_hold import hold_stop
127
+ from once_per_session import claim_turn_showing, is_turn_claimed
85
128
  from open_task_asks import claude_home, is_ask
86
129
  from open_tasks_transcript import TaskItem, TranscriptReplay, normalized_text, parsed_object, replayed_transcript
87
130
  from user_step_wording import file_waiting_phrase, waiting_phrase
131
+ from closing_reply_shapes import item_count_under, open_item_list, promised_report_phrase
132
+ from closing_reply_judge import JudgeVerdict, is_judge_available, judged_verdict, log_no_verdict
133
+ from turn_review_transcript import _last_assistant_message_text, _ReversedTranscript
134
+ from hooks_constants.closing_reply_judge_constants import (
135
+ MARKER_UNREADABLE_REASON,
136
+ NO_TURN_KEY_REASON,
137
+ TRANSCRIPT_UNREADABLE_REASON,
138
+ )
139
+ from hooks_constants.spawn_readiness_hook_constants import CODEX_TURN_ID_KEY
140
+ from hooks_constants.turn_review_gate_constants import REVIEW_CHILD_ENVIRONMENT_VARIABLE, REVIEW_CHILD_MARKER
88
141
  from hooks_constants.open_tasks_stop_gate_constants import (
142
+ ALL_OWN_REASON_OPENINGS,
89
143
  ALLOW_EXIT_CODE,
144
+ CLOSING_REPLY_HOLD_MARKER_NAME,
90
145
  COMPLETED_ITEMS_REASON_TEMPLATE,
91
146
  COMPLETED_STATUS,
92
147
  CURSOR_COMPLETED_STATUS,
@@ -97,6 +152,12 @@ from hooks_constants.open_tasks_stop_gate_constants import (
97
152
  INCOMPLETE_STATUSES,
98
153
  KEEP_REPLY_INSTRUCTION,
99
154
  NO_STEP_INSTRUCTION,
155
+ OPEN_ITEM_LIST_KEEP_CONDITION,
156
+ OPEN_ITEM_LIST_REASON_TEMPLATE,
157
+ PROMISED_REPORT_KEEP_CONDITION,
158
+ PROMISED_REPORT_REASON_TEMPLATE,
159
+ REWORKED_REPLY_INSTRUCTION,
160
+ SHORT_REPLY_INSTRUCTION,
100
161
  STOP_HOOK_ACTIVE_KEY,
101
162
  TASK_FILE_GLOB,
102
163
  TASK_ID_KEY,
@@ -167,7 +228,9 @@ def session_task_items(session_id: object, replay: TranscriptReplay) -> list[Tas
167
228
 
168
229
 
169
230
  def is_untracked_work_turn(replay: TranscriptReplay) -> bool:
170
- """Return True when the turn worked on an ask and made no tracker call."""
231
+ """Return True when the turn worked on an ask and made no tracker call in a session that has a tracker."""
232
+ if replay.lists_no_tracker_tool:
233
+ return False
171
234
  return replay.has_turn_work_tool and not replay.has_turn_tracker_write and is_ask(replay.turn_prompt_text)
172
235
 
173
236
 
@@ -208,6 +271,11 @@ def turn_waiting_phrase(all_hook_input_fields: dict[str, object], replay: Transc
208
271
  return next((each_phrase for each_phrase in all_file_phrases if each_phrase is not None), None)
209
272
 
210
273
 
274
+ def _has_readable_transcript(all_hook_input_fields: dict[str, object]) -> bool:
275
+ transcript_path = all_hook_input_fields.get(TRANSCRIPT_PATH_KEY)
276
+ return isinstance(transcript_path, str) and Path(transcript_path).is_file()
277
+
278
+
211
279
  def user_step_reasons(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> list[str]:
212
280
  """Return a reason for each thing a turn skipped before it told the user something waits on them.
213
281
 
@@ -220,8 +288,7 @@ def user_step_reasons(all_hook_input_fields: dict[str, object], replay: Transcri
220
288
 
221
289
  A session whose transcript cannot be read gives no reason.
222
290
  """
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():
291
+ if not _has_readable_transcript(all_hook_input_fields):
225
292
  return []
226
293
  all_reasons = [
227
294
  each_reason
@@ -246,14 +313,180 @@ def tracker_reasons(all_hook_input_fields: dict[str, object], replay: Transcript
246
313
  return all_reasons if stale_reason is None else [*all_reasons, stale_reason]
247
314
 
248
315
 
316
+ class ClosingReplyFinding(NamedTuple):
317
+ """One closing-reply shape the gate found: what it found and the steps, the line that ends the turn, and when to keep the reply."""
318
+
319
+ reason: str
320
+ closing_instruction: str
321
+ keep_condition: str
322
+
323
+
324
+ def _promise_finding(promise_phrase: str) -> ClosingReplyFinding:
325
+ return ClosingReplyFinding(
326
+ PROMISED_REPORT_REASON_TEMPLATE.format(phrase=promise_phrase),
327
+ REWORKED_REPLY_INSTRUCTION,
328
+ PROMISED_REPORT_KEEP_CONDITION,
329
+ )
330
+
331
+
332
+ def _list_finding(lead: str, item_count: int) -> ClosingReplyFinding:
333
+ return ClosingReplyFinding(
334
+ OPEN_ITEM_LIST_REASON_TEMPLATE.format(count=item_count, lead=lead),
335
+ SHORT_REPLY_INSTRUCTION,
336
+ OPEN_ITEM_LIST_KEEP_CONDITION,
337
+ )
338
+
339
+
340
+ def is_judged_payload(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> bool:
341
+ """Return True for a Claude Code stop on a host with ``claude`` on PATH, and False for Codex and Cursor stops.
342
+
343
+ A Codex stop is one whose payload carries ``turn_id`` or whose turn a Codex rollout record started.
344
+ """
345
+ if all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY) or all_hook_input_fields.get(CODEX_TURN_ID_KEY):
346
+ return False
347
+ if replay.is_codex_turn:
348
+ return False
349
+ return is_judge_available()
350
+
351
+
352
+ def _judged_reply_text(all_hook_input_fields: dict[str, object]) -> str:
353
+ payload_reply = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
354
+ if isinstance(payload_reply, str) and payload_reply.strip():
355
+ return payload_reply
356
+ return _last_assistant_message_text(_ReversedTranscript(all_hook_input_fields))
357
+
358
+
359
+ def _verdict_findings(verdict: JudgeVerdict, reply_text: str) -> list[ClosingReplyFinding]:
360
+ all_findings: list[ClosingReplyFinding] = []
361
+ if verdict.promise_span:
362
+ all_findings.append(_promise_finding(verdict.promise_span))
363
+ if verdict.list_span:
364
+ all_findings.append(_list_finding(verdict.list_span, item_count_under(reply_text, verdict.list_span)))
365
+ return all_findings
366
+
367
+
368
+ def _judged_findings(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> list[ClosingReplyFinding]:
369
+ if not _has_readable_transcript(all_hook_input_fields):
370
+ log_no_verdict(TRANSCRIPT_UNREADABLE_REASON)
371
+ return []
372
+ if replay.turn_key is None:
373
+ log_no_verdict(NO_TURN_KEY_REASON)
374
+ return []
375
+ is_claimed = is_turn_claimed(CLOSING_REPLY_HOLD_MARKER_NAME, all_hook_input_fields, replay.turn_key)
376
+ if is_claimed is None:
377
+ log_no_verdict(MARKER_UNREADABLE_REASON)
378
+ if is_claimed is not False:
379
+ return []
380
+ reply_text = _judged_reply_text(all_hook_input_fields)
381
+ if not reply_text:
382
+ return []
383
+ verdict = judged_verdict(replay.turn_prompt_text, reply_text, replay.has_turn_question_tool)
384
+ return [] if verdict is None else _verdict_findings(verdict, reply_text)
385
+
386
+
387
+ def closing_reply_findings(
388
+ all_hook_input_fields: dict[str, object], replay: TranscriptReplay
389
+ ) -> list[ClosingReplyFinding]:
390
+ """Return a finding for a promised later report and one for open items sent as a list in the closing reply.
391
+
392
+ ::
393
+
394
+ "The benchmark table will be posted when you get back." -> the promised report finding
395
+ "What I deferred:" over 5 items, no question call -> the open item list finding
396
+ the same list after an AskUserQuestion call -> []
397
+
398
+ A Claude Code stop on a host with ``claude`` on PATH asks the judge in
399
+ ``closing_reply_judge.py`` once, and only while this turn holds no
400
+ closing-reply hold yet. Its reply is ``last_assistant_message``, or the
401
+ transcript's last assistant text when that field is empty. A judge that
402
+ gives no verdict gives no finding. Codex and Cursor stops, and a host with
403
+ no ``claude``, use the phrase checks in ``closing_reply_shapes.py``. A
404
+ session whose transcript cannot be read gives no finding.
405
+ """
406
+ if is_judged_payload(all_hook_input_fields, replay):
407
+ return _judged_findings(all_hook_input_fields, replay)
408
+ reply_text = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
409
+ if not isinstance(reply_text, str) or not _has_readable_transcript(all_hook_input_fields):
410
+ return []
411
+ all_findings: list[ClosingReplyFinding] = []
412
+ promise_phrase = promised_report_phrase(reply_text, replay.turn_prompt_text)
413
+ if promise_phrase is not None:
414
+ all_findings.append(_promise_finding(promise_phrase))
415
+ item_list = None if replay.has_turn_question_tool else open_item_list(reply_text, replay.turn_prompt_text)
416
+ if item_list is not None:
417
+ all_findings.append(_list_finding(item_list.lead, item_list.item_count))
418
+ return all_findings
419
+
420
+
421
+ def _closing_lines(has_step_reason: bool, all_reply_findings: list[ClosingReplyFinding]) -> list[str]:
422
+ if all_reply_findings:
423
+ return [
424
+ all_reply_findings[-1].closing_instruction,
425
+ *(each_finding.keep_condition for each_finding in all_reply_findings),
426
+ ]
427
+ return [NO_STEP_INSTRUCTION if has_step_reason else KEEP_REPLY_INSTRUCTION]
428
+
429
+
249
430
  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."""
431
+ """Return one reason that carries every finding on the turn, or None when the turn may end.
432
+
433
+ ::
434
+
435
+ tracker finding only -> the finding, then "Then end the turn. Leave the reply as it stands."
436
+ promise and list findings -> both findings, the list's closing line, then both keep conditions
437
+
438
+ "end the turn" appears once in every reason.
439
+ """
251
440
  all_tracker_reasons = tracker_reasons(all_hook_input_fields, replay)
252
441
  all_step_reasons = user_step_reasons(all_hook_input_fields, replay)
253
- if not all_tracker_reasons and not all_step_reasons:
442
+ all_reply_findings = closing_reply_findings(all_hook_input_fields, replay)
443
+ all_reasons = [
444
+ *all_tracker_reasons,
445
+ *all_step_reasons,
446
+ *(each_finding.reason for each_finding in all_reply_findings),
447
+ ]
448
+ if not all_reasons:
254
449
  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])
450
+ return WORD_SEPARATOR.join([*all_reasons, *_closing_lines(bool(all_step_reasons), all_reply_findings)])
451
+
452
+
453
+ def _closing_reply_reason(all_reply_findings: list[ClosingReplyFinding]) -> str:
454
+ return WORD_SEPARATOR.join(
455
+ [*(each_finding.reason for each_finding in all_reply_findings), *_closing_lines(False, all_reply_findings)]
456
+ )
457
+
458
+
459
+ def _has_turn_hold_from_this_gate(replay: TranscriptReplay) -> bool:
460
+ return any(
461
+ each_opening in each_feedback
462
+ for each_feedback in replay.turn_stop_feedback_texts
463
+ for each_opening in ALL_OWN_REASON_OPENINGS
464
+ )
465
+
466
+
467
+ def continued_stop_reason(all_hook_input_fields: dict[str, object], replay: TranscriptReplay) -> str | None:
468
+ """Return the closing-reply reason for a Claude Code stop that a Stop hook already held, at most once per turn.
469
+
470
+ ::
471
+
472
+ another hook held, the reply promises a report, first time this turn -> the promised report reason
473
+ the same turn again -> None
474
+ a stop after this gate held the turn -> None
475
+ no turn key, a Cursor payload, or a marker that cannot be kept -> None
476
+
477
+ The turn key is the ``uuid`` of the prompt record that started the turn.
478
+ Tracker and user-step reasons stay off such a stop.
479
+ """
480
+ if all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY) or replay.turn_key is None:
481
+ return None
482
+ if _has_turn_hold_from_this_gate(replay):
483
+ return None
484
+ all_reply_findings = closing_reply_findings(all_hook_input_fields, replay)
485
+ if not all_reply_findings:
486
+ return None
487
+ if claim_turn_showing(CLOSING_REPLY_HOLD_MARKER_NAME, all_hook_input_fields, replay.turn_key) is not True:
488
+ return None
489
+ return _closing_reply_reason(all_reply_findings)
257
490
 
258
491
 
259
492
  def is_held_stop(all_hook_input_fields: dict[str, object]) -> bool:
@@ -268,11 +501,26 @@ def is_held_stop(all_hook_input_fields: dict[str, object]) -> bool:
268
501
  return has_sent_followup or (stop_status is not None and stop_status != CURSOR_COMPLETED_STATUS)
269
502
 
270
503
 
504
+ def _stop_block_reason(all_hook_input_fields: dict[str, object]) -> str | None:
505
+ if os.environ.get(REVIEW_CHILD_ENVIRONMENT_VARIABLE) == REVIEW_CHILD_MARKER:
506
+ return None
507
+ is_claude_held_stop = all_hook_input_fields.get(STOP_HOOK_ACTIVE_KEY) is True
508
+ if is_held_stop(all_hook_input_fields) and not is_claude_held_stop:
509
+ return None
510
+ replay = replayed_transcript(all_hook_input_fields.get(TRANSCRIPT_PATH_KEY))
511
+ if is_claude_held_stop:
512
+ return continued_stop_reason(all_hook_input_fields, replay)
513
+ block_reason = turn_block_reason(all_hook_input_fields, replay)
514
+ if block_reason is not None and replay.turn_key is not None:
515
+ claim_turn_showing(CLOSING_REPLY_HOLD_MARKER_NAME, all_hook_input_fields, replay.turn_key)
516
+ return block_reason
517
+
518
+
271
519
  def main() -> int:
272
520
  hook_input = read_hook_input_dictionary_from_stdin()
273
- if hook_input is None or is_held_stop(hook_input):
521
+ if hook_input is None:
274
522
  return ALLOW_EXIT_CODE
275
- block_reason = turn_block_reason(hook_input, replayed_transcript(hook_input.get(TRANSCRIPT_PATH_KEY)))
523
+ block_reason = _stop_block_reason(hook_input)
276
524
  if block_reason is None:
277
525
  return ALLOW_EXIT_CODE
278
526
  log_hook_block(Path(__file__).name, HOOK_EVENT_NAME, block_reason)
@@ -31,6 +31,18 @@ The replay also notes what the current turn did::
31
31
  word such as ``get``, ``list`` or ``read`` and no
32
32
  write word such as ``update``
33
33
  turn_sent_file_paths the paths the turn's SendUserFile calls sent
34
+ turn_key the ``uuid`` of the Claude Code prompt record that
35
+ started the turn, or None for a Codex turn or a
36
+ record with no ``uuid``
37
+ turn_stop_feedback_texts the text of each ``Stop hook feedback`` record
38
+ the turn holds
39
+ is_codex_turn a Codex ``response_item`` user message started the turn
40
+
41
+ Across the whole session, the replay also notes whether a tracker tool exists::
42
+
43
+ lists_no_tracker_tool a prompt_snapshot tools list and a deferred_tools_delta
44
+ both appeared, and no tracker name appeared in any
45
+ listing, deferred_tools_record, or tracker call
34
46
 
35
47
  A turn starts at the last user prompt record. A tool result, a record flagged
36
48
  ``isMeta``, ``isSidechain`` or ``isCompactSummary``, and a ``Stop hook feedback``
@@ -56,6 +68,7 @@ if hooks_root_directory not in sys.path:
56
68
  from hooks_constants.open_tasks_stop_gate_constants import (
57
69
  ASSISTANT_RECORD_TYPE,
58
70
  ALL_QUESTION_TOOL_NAMES,
71
+ ALL_TRACKER_TOOL_LISTING_NAMES,
59
72
  ALL_TRACKER_TOOL_NAMES,
60
73
  CCD_PLAN_ADVANCE_KEY,
61
74
  CCD_PLAN_CONTENT_KEY,
@@ -74,6 +87,7 @@ from hooks_constants.open_tasks_stop_gate_constants import (
74
87
  COMPLETED_STATUS,
75
88
  CONTENT_KEY,
76
89
  CREATED_TASK_ID_GROUP_INDEX,
90
+ DEFERRED_TOOLS_DELTA_ATTACHMENT_TYPE,
77
91
  DYNAMIC_TOOL_ARGUMENTS_KEY,
78
92
  DYNAMIC_TOOL_CALL_NAME,
79
93
  DYNAMIC_TOOL_NAME_KEY,
@@ -81,7 +95,9 @@ from hooks_constants.open_tasks_stop_gate_constants import (
81
95
  INCOMPLETE_STATUSES,
82
96
  IN_PROGRESS_STATUS,
83
97
  PENDING_STATUS,
98
+ PROMPT_SNAPSHOT_ATTACHMENT_TYPE,
84
99
  RECORD_TYPE_KEY,
100
+ RECORD_UUID_KEY,
85
101
  TASK_CREATED_PATTERN,
86
102
  TASK_CREATE_TOOL_NAME,
87
103
  TASK_ID_KEY,
@@ -116,6 +132,8 @@ from open_tasks_transcript_records import (
116
132
  is_read_tool_name,
117
133
  send_call_file_paths,
118
134
  is_assistant_record,
135
+ stop_feedback_text,
136
+ listed_tool_names,
119
137
  )
120
138
 
121
139
 
@@ -240,6 +258,22 @@ class TranscriptReplay:
240
258
  self.has_turn_question_tool = False
241
259
  self.has_turn_read_tool = False
242
260
  self.turn_sent_file_paths: list[str] = []
261
+ self.turn_key: str | None = None
262
+ self.turn_stop_feedback_texts: list[str] = []
263
+ self.is_codex_turn = False
264
+ self.all_tool_listing_types: set[str] = set()
265
+ self.has_tracker_tool = False
266
+
267
+ @property
268
+ def lists_no_tracker_tool(self) -> bool:
269
+ """Return True when the session listed its inline and deferred tools and no tracker ran or appeared."""
270
+ has_full_listing = {PROMPT_SNAPSHOT_ATTACHMENT_TYPE, DEFERRED_TOOLS_DELTA_ATTACHMENT_TYPE} <= self.all_tool_listing_types
271
+ return has_full_listing and not self.has_tracker_tool
272
+
273
+ def note_tool_listing(self, listing_type: str, all_tool_names: list[str]) -> None:
274
+ self.all_tool_listing_types.add(listing_type)
275
+ if not ALL_TRACKER_TOOL_LISTING_NAMES.isdisjoint(all_tool_names):
276
+ self.has_tracker_tool = True
243
277
 
244
278
  def start_turn(self, prompt_text: str) -> None:
245
279
  self.turn_prompt_text = prompt_text
@@ -248,18 +282,35 @@ class TranscriptReplay:
248
282
  self.has_turn_question_tool = False
249
283
  self.has_turn_read_tool = False
250
284
  self.turn_sent_file_paths = []
285
+ self.turn_key = None
286
+ self.turn_stop_feedback_texts = []
287
+ self.is_codex_turn = False
251
288
 
252
289
  def apply_record(self, all_record_fields: dict[str, object]) -> None:
253
290
  prompt_text = codex_prompt_text(all_record_fields)
254
- if prompt_text is None:
255
- prompt_text = claude_prompt_text(all_record_fields)
256
291
  if prompt_text is not None:
257
292
  self.start_turn(prompt_text)
293
+ self.is_codex_turn = True
294
+ return
295
+ prompt_text = claude_prompt_text(all_record_fields)
296
+ if prompt_text is not None:
297
+ self.start_turn(prompt_text)
298
+ prompt_uuid = all_record_fields.get(RECORD_UUID_KEY)
299
+ self.turn_key = prompt_uuid if isinstance(prompt_uuid, str) and prompt_uuid else None
300
+ return
301
+ feedback_text = stop_feedback_text(all_record_fields)
302
+ if feedback_text is not None:
303
+ self.turn_stop_feedback_texts.append(feedback_text)
304
+ return
305
+ tool_listing = listed_tool_names(all_record_fields)
306
+ if tool_listing is not None:
307
+ self.note_tool_listing(*tool_listing)
258
308
  return
259
309
  plan_items = codex_plan_items(all_record_fields)
260
310
  if plan_items is not None:
261
311
  self.latest_items = plan_items
262
312
  self.has_turn_tracker_write = True
313
+ self.has_tracker_tool = True
263
314
  return
264
315
  if is_codex_question_call(all_record_fields):
265
316
  self.has_turn_question_tool = True
@@ -275,6 +326,7 @@ class TranscriptReplay:
275
326
  if is_typed_assistant_record and each_block.get(TOOL_NAME_KEY) == CCD_PLAN_TOOL_NAME and isinstance(plan_input, dict):
276
327
  self.apply_desktop_plan(plan_input)
277
328
  self.has_turn_tracker_write = True
329
+ self.has_tracker_tool = True
278
330
  else:
279
331
  self.apply_block(each_block, is_from_assistant)
280
332
 
@@ -328,6 +380,7 @@ class TranscriptReplay:
328
380
  self.has_turn_read_tool = True
329
381
  if tool_name in ALL_TRACKER_TOOL_NAMES:
330
382
  self.has_turn_tracker_write = True
383
+ self.has_tracker_tool = True
331
384
  elif is_work_tool_name(tool_name):
332
385
  self.has_turn_work_tool = True
333
386
 
@@ -1,7 +1,8 @@
1
1
  """Read a transcript file into records, and read what one record holds.
2
2
 
3
3
  One record can hold the prompt text that starts a turn, a tool call that is work,
4
- a read, or a question card, or the files a ``SendUserFile`` call sends.
4
+ a read, or a question card, the files a ``SendUserFile`` call sends, or the
5
+ names of the tools a Claude Code session lists.
5
6
  ``open_tasks_transcript`` folds these readers over every record. Its module
6
7
  docstring lists which records start a turn and which tool calls count as work.
7
8
  """
@@ -15,8 +16,15 @@ from pathlib import Path
15
16
  from hooks_constants.send_user_file_worktree_root_gate_constants import SEND_USER_FILE_TOOL_NAME
16
17
  from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
17
18
  from hooks_constants.open_tasks_stop_gate_constants import (
19
+ ALL_DEFERRED_TOOLS_DELTA_NAME_KEYS,
18
20
  ALL_SKIPPED_PROMPT_FLAGS,
19
21
  ALL_CODEX_TOOL_CALL_TYPES,
22
+ ATTACHMENT_KEY,
23
+ DEFERRED_TOOLS_DELTA_ATTACHMENT_TYPE,
24
+ DEFERRED_TOOLS_RECORD_ATTACHMENT_TYPE,
25
+ DEFERRED_TOOLS_RECORD_ENTRIES_KEY,
26
+ PROMPT_SNAPSHOT_ATTACHMENT_TYPE,
27
+ PROMPT_SNAPSHOT_TOOLS_KEY,
20
28
  ALL_NON_WORK_TOOL_NAMES,
21
29
  ALL_QUESTION_TOOL_NAMES,
22
30
  ALL_READ_TOOL_NAMES,
@@ -113,6 +121,16 @@ def claude_prompt_text(all_record_fields: dict[str, object]) -> str | None:
113
121
  return prompt_text
114
122
 
115
123
 
124
+ def stop_feedback_text(all_record_fields: dict[str, object]) -> str | None:
125
+ """Return the text of a Claude Code ``Stop hook feedback`` user record, flagged ``isMeta`` or not, or None."""
126
+ message_body = all_record_fields.get(MESSAGE_KEY)
127
+ if USER_RECORD_TYPE != all_record_fields.get(RECORD_TYPE_KEY) or not isinstance(message_body, dict):
128
+ return None
129
+ content_value = message_body.get(CONTENT_KEY)
130
+ feedback_text = content_value if isinstance(content_value, str) else _text_of_blocks(_content_blocks(all_record_fields))
131
+ return feedback_text if feedback_text.lstrip().startswith(STOP_HOOK_FEEDBACK_PREFIX) else None
132
+
133
+
116
134
  def _codex_payload(all_record_fields: dict[str, object]) -> dict[str, object] | None:
117
135
  payload_body = all_record_fields.get(CODEX_PAYLOAD_KEY)
118
136
  if all_record_fields.get(RECORD_TYPE_KEY) != CODEX_RESPONSE_ITEM_TYPE or not isinstance(payload_body, dict):
@@ -204,6 +222,54 @@ def send_call_file_paths(tool_name: str, all_input_fields: dict[str, object]) ->
204
222
  return [each_path for each_path in all_sent_files if isinstance(each_path, str)]
205
223
 
206
224
 
225
+ def _entry_names(all_entries: object) -> list[str]:
226
+ if not isinstance(all_entries, list):
227
+ return []
228
+ return [
229
+ each_entry[TOOL_NAME_KEY]
230
+ for each_entry in all_entries
231
+ if isinstance(each_entry, dict) and isinstance(each_entry.get(TOOL_NAME_KEY), str)
232
+ ]
233
+
234
+
235
+ def listed_tool_names(all_record_fields: dict[str, object]) -> tuple[str, list[str]] | None:
236
+ """Return the attachment type and tool names of a Claude Code record that lists the session's tools.
237
+
238
+ ::
239
+
240
+ prompt_snapshot with a tools list -> ("prompt_snapshot", the inline tool names)
241
+ deferred_tools_delta -> ("deferred_tools_delta", the added, readded,
242
+ surfaced, and loaded names)
243
+ deferred_tools_record -> ("deferred_tools_record", the names ToolSearch loaded)
244
+ prompt_snapshot with no tools list -> None
245
+ any other record -> None
246
+
247
+ Names come only from these fields, so a tool name inside prose never counts.
248
+ """
249
+ attachment_body = all_record_fields.get(ATTACHMENT_KEY)
250
+ if not isinstance(attachment_body, dict):
251
+ return None
252
+ attachment_type = attachment_body.get(RECORD_TYPE_KEY)
253
+ if attachment_type == PROMPT_SNAPSHOT_ATTACHMENT_TYPE:
254
+ all_inline_tools = attachment_body.get(PROMPT_SNAPSHOT_TOOLS_KEY)
255
+ if not isinstance(all_inline_tools, list):
256
+ return None
257
+ return attachment_type, _entry_names(all_inline_tools)
258
+ if attachment_type == DEFERRED_TOOLS_RECORD_ATTACHMENT_TYPE:
259
+ return attachment_type, _entry_names(attachment_body.get(DEFERRED_TOOLS_RECORD_ENTRIES_KEY))
260
+ if attachment_type == DEFERRED_TOOLS_DELTA_ATTACHMENT_TYPE:
261
+ all_delta_names = [
262
+ each_name
263
+ for each_key in ALL_DEFERRED_TOOLS_DELTA_NAME_KEYS
264
+ for each_delta_value in [attachment_body.get(each_key)]
265
+ if isinstance(each_delta_value, list)
266
+ for each_name in each_delta_value
267
+ if isinstance(each_name, str)
268
+ ]
269
+ return attachment_type, all_delta_names
270
+ return None
271
+
272
+
207
273
  def is_assistant_record(all_record_fields: dict[str, object]) -> bool:
208
274
  """Return True for a record the assistant wrote, by its type, its role, or its message role."""
209
275
  message_body = all_record_fields.get(MESSAGE_KEY)