claude-dev-env 8.117.5 → 8.118.1

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.
@@ -100,6 +100,7 @@ export const EVER_REGISTERED_HOOK_RELATIVE_PATHS = new Set([
100
100
  'blocking/subagent_model_routing.mjs',
101
101
  'blocking/subprocess_budget_completeness.py',
102
102
  'blocking/task_subject_length_gate.py',
103
+ 'blocking/task_subject_outcome_gate.py',
103
104
  'blocking/tdd-enforcer.py',
104
105
  'blocking/tdd_enforcer.py',
105
106
  'blocking/test-preflight-check.py',
@@ -14,6 +14,8 @@ Work every ask from the user now, without pause, until it is done with proof you
14
14
  - Record each ask as one item in the session tracker: `TaskCreate`, `TodoWrite`, or the Codex `update_plan` tool. The user follows your work there.
15
15
  - Keep each item's status current as the work moves: in progress when you start it, completed only after you saw the proof. A long turn updates the list at each step, so the list never lags the work.
16
16
  - An item blocked on the user stays open, and the reply says what the user must give.
17
+ - Name each item by its outcome in the user's words, so the user sees at a glance where the work stands and what is left. Keep internal procedure steps, playbook step names, and skill names out of the list the user follows. Put them in a private checklist file, such as `todo.md` in the work folder.
18
+ - When the user asks where things stand, answer with what is done, what is being built, what is left, and what needs the user.
17
19
 
18
20
  ## Completion reports
19
21
 
@@ -45,6 +47,8 @@ The gate holds a turn once when all three hold:
45
47
 
46
48
  The gate never reads the reply text. A held turn passes, so the gate adds at most one step to a turn.
47
49
 
50
+ In Claude Code, `task_subject_outcome_gate.py` denies a task list item named as a procedure step. [Conduct gates](../../hooks/features/conduct-gates.md) lists what it matches.
51
+
48
52
  In Claude Code, `tracking_nudge.py` runs on `UserPromptSubmit`. For the session's first prompt that asks for work, and the first after each compaction, it adds one note that asks for an item in the session's task list tool, so the agent tracks the ask before it starts. The note never blocks.
49
53
 
50
54
  ## Cursor
@@ -44,7 +44,6 @@ TodoWrite input under ``arguments``; that call counts as the TodoWrite call.
44
44
 
45
45
  from __future__ import annotations
46
46
 
47
- import json
48
47
  import re
49
48
  import sys
50
49
  from pathlib import Path
@@ -54,19 +53,10 @@ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
54
53
  if hooks_root_directory not in sys.path:
55
54
  sys.path.insert(0, hooks_root_directory)
56
55
 
57
- from hooks_constants.send_user_file_worktree_root_gate_constants import SEND_USER_FILE_TOOL_NAME
58
- from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
59
56
  from hooks_constants.open_tasks_stop_gate_constants import (
60
- ALL_SKIPPED_PROMPT_FLAGS,
61
57
  ASSISTANT_RECORD_TYPE,
62
- ALL_CODEX_TOOL_CALL_TYPES,
63
- ALL_NON_WORK_TOOL_NAMES,
64
58
  ALL_QUESTION_TOOL_NAMES,
65
- ALL_READ_TOOL_NAMES,
66
- ALL_READ_WORDS,
67
59
  ALL_TRACKER_TOOL_NAMES,
68
- ALL_WRITE_WORDS,
69
- ASSISTANT_ROLE,
70
60
  CCD_PLAN_ADVANCE_KEY,
71
61
  CCD_PLAN_CONTENT_KEY,
72
62
  CCD_PLAN_DONE_KEY,
@@ -76,8 +66,6 @@ from hooks_constants.open_tasks_stop_gate_constants import (
76
66
  CCD_PLAN_TOOL_NAME,
77
67
  CODEX_ARGUMENTS_KEY,
78
68
  CODEX_FUNCTION_CALL_TYPE,
79
- CODEX_LOCAL_SHELL_CALL_TYPE,
80
- CODEX_MESSAGE_TYPE,
81
69
  CODEX_PAYLOAD_KEY,
82
70
  CODEX_PLAN_KEY,
83
71
  CODEX_PLAN_TOOL_NAME,
@@ -92,19 +80,14 @@ from hooks_constants.open_tasks_stop_gate_constants import (
92
80
  FIRST_ITEM_NUMBER,
93
81
  INCOMPLETE_STATUSES,
94
82
  IN_PROGRESS_STATUS,
95
- MESSAGE_KEY,
96
83
  PENDING_STATUS,
97
84
  RECORD_TYPE_KEY,
98
- ROLE_KEY,
99
- SENT_FILES_KEY,
100
- STOP_HOOK_FEEDBACK_PREFIX,
101
85
  TASK_CREATED_PATTERN,
102
86
  TASK_CREATE_TOOL_NAME,
103
87
  TASK_ID_KEY,
104
88
  TASK_STATUS_KEY,
105
89
  TASK_SUBJECT_KEY,
106
90
  TASK_UPDATE_ID_KEY,
107
- SESSION_TITLE_TOOL_SUFFIX,
108
91
  TASK_UPDATE_TOOL_NAME,
109
92
  TEXT_KEY,
110
93
  TODOS_KEY,
@@ -113,18 +96,27 @@ from hooks_constants.open_tasks_stop_gate_constants import (
113
96
  TODO_MERGE_KEY,
114
97
  TODO_WRITE_TOOL_NAME,
115
98
  TOOL_INPUT_KEY,
116
- RECORD_SEPARATOR,
117
- TOOL_NAME_SERVER_SEPARATOR,
118
- TOOL_NAME_WORD_BREAK_PATTERN,
119
99
  TOOL_NAME_KEY,
120
100
  TOOL_RESULT_BLOCK_TYPE,
121
101
  TOOL_USE_BLOCK_TYPE,
122
102
  TOOL_USE_ID_KEY,
123
- USER_RECORD_TYPE,
124
- USER_ROLE,
125
- UTF8_ENCODING,
126
103
  WORD_SEPARATOR,
127
104
  )
105
+ from open_tasks_transcript_records import (
106
+ normalized_text,
107
+ parsed_object,
108
+ _transcript_records,
109
+ _content_blocks,
110
+ claude_prompt_text,
111
+ codex_prompt_text,
112
+ is_codex_work_call,
113
+ is_codex_read_call,
114
+ is_codex_question_call,
115
+ is_work_tool_name,
116
+ is_read_tool_name,
117
+ send_call_file_paths,
118
+ is_assistant_record,
119
+ )
128
120
 
129
121
 
130
122
  class TaskItem(NamedTuple):
@@ -141,42 +133,6 @@ class TaskItem(NamedTuple):
141
133
  status: str
142
134
 
143
135
 
144
- def normalized_text(text: str) -> str:
145
- """Return the text lowercased with each run of whitespace collapsed to one space."""
146
- return WORD_SEPARATOR.join(text.lower().split())
147
-
148
-
149
- def parsed_object(json_text: str) -> dict[str, object] | None:
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
- """
154
- try:
155
- parsed_value = json.loads(json_text)
156
- except (ValueError, RecursionError):
157
- return None
158
- return parsed_value if isinstance(parsed_value, dict) else None
159
-
160
-
161
- def _transcript_records(transcript_path: object) -> list[dict[str, object]]:
162
- if not isinstance(transcript_path, str):
163
- return []
164
- try:
165
- transcript_text = Path(transcript_path).read_text(encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
166
- except (OSError, ValueError):
167
- return []
168
- all_records = (parsed_object(each_line) for each_line in transcript_text.split(RECORD_SEPARATOR))
169
- return [each_record for each_record in all_records if each_record is not None]
170
-
171
-
172
- def _content_blocks(all_record_fields: dict[str, object]) -> list[dict[str, object]]:
173
- message_body = all_record_fields.get(MESSAGE_KEY)
174
- content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
175
- if not isinstance(content_value, list):
176
- return []
177
- return [each_block for each_block in content_value if isinstance(each_block, dict)]
178
-
179
-
180
136
  def _result_text(all_block_fields: dict[str, object]) -> str:
181
137
  result_content = all_block_fields.get(CONTENT_KEY)
182
138
  if isinstance(result_content, str):
@@ -188,133 +144,6 @@ def _result_text(all_block_fields: dict[str, object]) -> str:
188
144
  )
189
145
 
190
146
 
191
- def _text_of_blocks(all_blocks: list[dict[str, object]]) -> str:
192
- return WORD_SEPARATOR.join(
193
- str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if isinstance(each_block.get(TEXT_KEY), str)
194
- )
195
-
196
-
197
- def claude_prompt_text(all_record_fields: dict[str, object]) -> str | None:
198
- """Return the prompt text of a record that starts a turn, or None for any other record."""
199
- message_body = all_record_fields.get(MESSAGE_KEY)
200
- message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
201
- if USER_RECORD_TYPE != all_record_fields.get(RECORD_TYPE_KEY) and USER_ROLE not in (all_record_fields.get(ROLE_KEY), message_role):
202
- return None
203
- if any(all_record_fields.get(each_flag) for each_flag in ALL_SKIPPED_PROMPT_FLAGS):
204
- return None
205
- content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
206
- if isinstance(content_value, str):
207
- prompt_text = content_value
208
- else:
209
- all_blocks = _content_blocks(all_record_fields)
210
- if any(each_block.get(RECORD_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE for each_block in all_blocks):
211
- return None
212
- if any(each_block.get(RECORD_TYPE_KEY) != TEXT_KEY for each_block in all_blocks):
213
- return _text_of_blocks(all_blocks)
214
- prompt_text = _text_of_blocks(all_blocks)
215
- if not prompt_text.strip() or prompt_text.lstrip().startswith(STOP_HOOK_FEEDBACK_PREFIX):
216
- return None
217
- return prompt_text
218
-
219
-
220
- def _codex_payload(all_record_fields: dict[str, object]) -> dict[str, object] | None:
221
- payload_body = all_record_fields.get(CODEX_PAYLOAD_KEY)
222
- if all_record_fields.get(RECORD_TYPE_KEY) != CODEX_RESPONSE_ITEM_TYPE or not isinstance(payload_body, dict):
223
- return None
224
- return payload_body
225
-
226
-
227
- def codex_prompt_text(all_record_fields: dict[str, object]) -> str | None:
228
- """Return the text of a Codex user message record, or None for any other record."""
229
- payload_body = _codex_payload(all_record_fields)
230
- if payload_body is None or payload_body.get(RECORD_TYPE_KEY) != CODEX_MESSAGE_TYPE or payload_body.get(ROLE_KEY) != USER_ROLE:
231
- return None
232
- content_value = payload_body.get(CONTENT_KEY)
233
- if isinstance(content_value, str):
234
- return content_value
235
- all_blocks = [each_block for each_block in content_value if isinstance(each_block, dict)] if isinstance(content_value, list) else []
236
- return _text_of_blocks(all_blocks)
237
-
238
-
239
- def is_codex_work_call(all_record_fields: dict[str, object]) -> bool:
240
- """Return True for a Codex tool call record other than ``update_plan`` or a question card call."""
241
- payload_body = _codex_payload(all_record_fields)
242
- if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
243
- return False
244
- tool_name = payload_body.get(TOOL_NAME_KEY)
245
- return tool_name != CODEX_PLAN_TOOL_NAME and is_work_tool_name(tool_name)
246
-
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
-
258
- def is_codex_question_call(all_record_fields: dict[str, object]) -> bool:
259
- """Return True for a Codex tool call record that sends a question card."""
260
- payload_body = _codex_payload(all_record_fields)
261
- if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
262
- return False
263
- return payload_body.get(TOOL_NAME_KEY) in ALL_QUESTION_TOOL_NAMES
264
-
265
-
266
- def is_work_tool_name(tool_name: object) -> bool:
267
- """Return True for a tool name other than a non-work tool or the session title tool."""
268
- return not (
269
- isinstance(tool_name, str)
270
- and (tool_name in ALL_NON_WORK_TOOL_NAMES or tool_name.endswith(SESSION_TITLE_TOOL_SUFFIX))
271
- )
272
-
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
-
311
- def is_assistant_record(all_record_fields: dict[str, object]) -> bool:
312
- """Return True for a record the assistant wrote, by its type, its role, or its message role."""
313
- message_body = all_record_fields.get(MESSAGE_KEY)
314
- message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
315
- return ASSISTANT_ROLE in (all_record_fields.get(ROLE_KEY), all_record_fields.get(RECORD_TYPE_KEY), message_role)
316
-
317
-
318
147
  def _numbered_items(all_entries: object, subject_key: str) -> list[TaskItem]:
319
148
  if not isinstance(all_entries, list):
320
149
  return []
@@ -0,0 +1,211 @@
1
+ """Read a transcript file into records, and read what one record holds.
2
+
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.
5
+ ``open_tasks_transcript`` folds these readers over every record. Its module
6
+ docstring lists which records start a turn and which tool calls count as work.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import json
12
+ import re
13
+ from pathlib import Path
14
+
15
+ from hooks_constants.send_user_file_worktree_root_gate_constants import SEND_USER_FILE_TOOL_NAME
16
+ from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY
17
+ from hooks_constants.open_tasks_stop_gate_constants import (
18
+ ALL_SKIPPED_PROMPT_FLAGS,
19
+ ALL_CODEX_TOOL_CALL_TYPES,
20
+ ALL_NON_WORK_TOOL_NAMES,
21
+ ALL_QUESTION_TOOL_NAMES,
22
+ ALL_READ_TOOL_NAMES,
23
+ ALL_READ_WORDS,
24
+ ALL_WRITE_WORDS,
25
+ ASSISTANT_ROLE,
26
+ CODEX_LOCAL_SHELL_CALL_TYPE,
27
+ CODEX_MESSAGE_TYPE,
28
+ CODEX_PAYLOAD_KEY,
29
+ CODEX_PLAN_TOOL_NAME,
30
+ CODEX_RESPONSE_ITEM_TYPE,
31
+ CONTENT_KEY,
32
+ MESSAGE_KEY,
33
+ RECORD_TYPE_KEY,
34
+ ROLE_KEY,
35
+ SENT_FILES_KEY,
36
+ STOP_HOOK_FEEDBACK_PREFIX,
37
+ SESSION_TITLE_TOOL_SUFFIX,
38
+ TEXT_KEY,
39
+ RECORD_SEPARATOR,
40
+ TOOL_NAME_SERVER_SEPARATOR,
41
+ TOOL_NAME_WORD_BREAK_PATTERN,
42
+ TOOL_NAME_KEY,
43
+ TOOL_RESULT_BLOCK_TYPE,
44
+ USER_RECORD_TYPE,
45
+ USER_ROLE,
46
+ UTF8_ENCODING,
47
+ WORD_SEPARATOR,
48
+ )
49
+
50
+
51
+ def normalized_text(text: str) -> str:
52
+ """Return the text lowercased with each run of whitespace collapsed to one space."""
53
+ return WORD_SEPARATOR.join(text.lower().split())
54
+
55
+
56
+ def parsed_object(json_text: str) -> dict[str, object] | None:
57
+ """Return the JSON object in the text, or None for anything else.
58
+
59
+ Text that is no JSON, or JSON nested too deep to parse, is None.
60
+ """
61
+ try:
62
+ parsed_value = json.loads(json_text)
63
+ except (ValueError, RecursionError):
64
+ return None
65
+ return parsed_value if isinstance(parsed_value, dict) else None
66
+
67
+
68
+ def _transcript_records(transcript_path: object) -> list[dict[str, object]]:
69
+ if not isinstance(transcript_path, str):
70
+ return []
71
+ try:
72
+ transcript_text = Path(transcript_path).read_text(encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY)
73
+ except (OSError, ValueError):
74
+ return []
75
+ all_records = (parsed_object(each_line) for each_line in transcript_text.split(RECORD_SEPARATOR))
76
+ return [each_record for each_record in all_records if each_record is not None]
77
+
78
+
79
+ def _content_blocks(all_record_fields: dict[str, object]) -> list[dict[str, object]]:
80
+ message_body = all_record_fields.get(MESSAGE_KEY)
81
+ content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
82
+ if not isinstance(content_value, list):
83
+ return []
84
+ return [each_block for each_block in content_value if isinstance(each_block, dict)]
85
+
86
+
87
+ def _text_of_blocks(all_blocks: list[dict[str, object]]) -> str:
88
+ return WORD_SEPARATOR.join(
89
+ str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if isinstance(each_block.get(TEXT_KEY), str)
90
+ )
91
+
92
+
93
+ def claude_prompt_text(all_record_fields: dict[str, object]) -> str | None:
94
+ """Return the prompt text of a record that starts a turn, or None for any other record."""
95
+ message_body = all_record_fields.get(MESSAGE_KEY)
96
+ message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
97
+ if USER_RECORD_TYPE != all_record_fields.get(RECORD_TYPE_KEY) and USER_ROLE not in (all_record_fields.get(ROLE_KEY), message_role):
98
+ return None
99
+ if any(all_record_fields.get(each_flag) for each_flag in ALL_SKIPPED_PROMPT_FLAGS):
100
+ return None
101
+ content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
102
+ if isinstance(content_value, str):
103
+ prompt_text = content_value
104
+ else:
105
+ all_blocks = _content_blocks(all_record_fields)
106
+ if any(each_block.get(RECORD_TYPE_KEY) == TOOL_RESULT_BLOCK_TYPE for each_block in all_blocks):
107
+ return None
108
+ if any(each_block.get(RECORD_TYPE_KEY) != TEXT_KEY for each_block in all_blocks):
109
+ return _text_of_blocks(all_blocks)
110
+ prompt_text = _text_of_blocks(all_blocks)
111
+ if not prompt_text.strip() or prompt_text.lstrip().startswith(STOP_HOOK_FEEDBACK_PREFIX):
112
+ return None
113
+ return prompt_text
114
+
115
+
116
+ def _codex_payload(all_record_fields: dict[str, object]) -> dict[str, object] | None:
117
+ payload_body = all_record_fields.get(CODEX_PAYLOAD_KEY)
118
+ if all_record_fields.get(RECORD_TYPE_KEY) != CODEX_RESPONSE_ITEM_TYPE or not isinstance(payload_body, dict):
119
+ return None
120
+ return payload_body
121
+
122
+
123
+ def codex_prompt_text(all_record_fields: dict[str, object]) -> str | None:
124
+ """Return the text of a Codex user message record, or None for any other record."""
125
+ payload_body = _codex_payload(all_record_fields)
126
+ if payload_body is None or payload_body.get(RECORD_TYPE_KEY) != CODEX_MESSAGE_TYPE or payload_body.get(ROLE_KEY) != USER_ROLE:
127
+ return None
128
+ content_value = payload_body.get(CONTENT_KEY)
129
+ if isinstance(content_value, str):
130
+ return content_value
131
+ all_blocks = [each_block for each_block in content_value if isinstance(each_block, dict)] if isinstance(content_value, list) else []
132
+ return _text_of_blocks(all_blocks)
133
+
134
+
135
+ def is_codex_work_call(all_record_fields: dict[str, object]) -> bool:
136
+ """Return True for a Codex tool call record other than ``update_plan`` or a question card call."""
137
+ payload_body = _codex_payload(all_record_fields)
138
+ if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
139
+ return False
140
+ tool_name = payload_body.get(TOOL_NAME_KEY)
141
+ return tool_name != CODEX_PLAN_TOOL_NAME and is_work_tool_name(tool_name)
142
+
143
+
144
+ def is_codex_read_call(all_record_fields: dict[str, object]) -> bool:
145
+ """Return True for a Codex tool call record whose tool can read state; a ``local_shell_call`` carries no name and counts."""
146
+ payload_body = _codex_payload(all_record_fields)
147
+ if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
148
+ return False
149
+ if payload_body.get(RECORD_TYPE_KEY) == CODEX_LOCAL_SHELL_CALL_TYPE:
150
+ return True
151
+ return is_read_tool_name(payload_body.get(TOOL_NAME_KEY))
152
+
153
+
154
+ def is_codex_question_call(all_record_fields: dict[str, object]) -> bool:
155
+ """Return True for a Codex tool call record that sends a question card."""
156
+ payload_body = _codex_payload(all_record_fields)
157
+ if payload_body is None or payload_body.get(RECORD_TYPE_KEY) not in ALL_CODEX_TOOL_CALL_TYPES:
158
+ return False
159
+ return payload_body.get(TOOL_NAME_KEY) in ALL_QUESTION_TOOL_NAMES
160
+
161
+
162
+ def is_work_tool_name(tool_name: object) -> bool:
163
+ """Return True for a tool name other than a non-work tool or the session title tool."""
164
+ return not (
165
+ isinstance(tool_name, str)
166
+ and (tool_name in ALL_NON_WORK_TOOL_NAMES or tool_name.endswith(SESSION_TITLE_TOOL_SUFFIX))
167
+ )
168
+
169
+
170
+ def is_read_tool_name(tool_name: object) -> bool:
171
+ """Return True for a tool that can read state.
172
+
173
+ ::
174
+
175
+ Bash, Read, WebFetch, Agent, shell -> True
176
+ mcp__github__pull_request_read -> True
177
+ mcp__claude-code-remote__get_session -> True
178
+ ReadMcpResourceTool, mcp__x__getIssue -> True
179
+ Write, SendUserFile, TaskUpdate -> False
180
+ TaskList, TaskGet -> False
181
+ mcp__tracker__update_status, AppendLog -> False
182
+ mcp__logs__write_entry -> False
183
+
184
+ A name counts when one of its words is a read word and none is a write
185
+ word. Only the part after the last double underscore is read, so a server
186
+ name never decides it. Words are split at underscores, hyphens, and a
187
+ capital that follows a lower-case letter or a digit. A tool that is no work tool never counts: TaskList and TaskGet read
188
+ the task list itself, and ToolSearch and the question tools read no state.
189
+ """
190
+ if not isinstance(tool_name, str) or tool_name in ALL_NON_WORK_TOOL_NAMES:
191
+ return False
192
+ if tool_name in ALL_READ_TOOL_NAMES:
193
+ return True
194
+ action_name = tool_name.rsplit(TOOL_NAME_SERVER_SEPARATOR, 1)[-1]
195
+ all_name_words = {each_word.lower() for each_word in re.split(TOOL_NAME_WORD_BREAK_PATTERN, action_name)}
196
+ return not ALL_READ_WORDS.isdisjoint(all_name_words) and ALL_WRITE_WORDS.isdisjoint(all_name_words)
197
+
198
+
199
+ def send_call_file_paths(tool_name: str, all_input_fields: dict[str, object]) -> list[str]:
200
+ """Return the file paths a SendUserFile call sends, or an empty list for any other call."""
201
+ all_sent_files = all_input_fields.get(SENT_FILES_KEY)
202
+ if tool_name != SEND_USER_FILE_TOOL_NAME or not isinstance(all_sent_files, list):
203
+ return []
204
+ return [each_path for each_path in all_sent_files if isinstance(each_path, str)]
205
+
206
+
207
+ def is_assistant_record(all_record_fields: dict[str, object]) -> bool:
208
+ """Return True for a record the assistant wrote, by its type, its role, or its message role."""
209
+ message_body = all_record_fields.get(MESSAGE_KEY)
210
+ message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
211
+ return ASSISTANT_ROLE in (all_record_fields.get(ROLE_KEY), all_record_fields.get(RECORD_TYPE_KEY), message_role)
@@ -0,0 +1,110 @@
1
+ #!/usr/bin/env python3
2
+ """PreToolUse hook that keeps procedure steps out of the task list the user follows.
3
+
4
+ The gate reads each subject a TaskCreate or TaskUpdate call sets, and the
5
+ content of each item a TodoWrite call writes. It denies the call when a subject
6
+ carries one of these markers:
7
+
8
+ - It starts with a procedure step label: step, phase, stage, part, feature,
9
+ bug fix, refactoring, or playbook, then a number or a range of one or two
10
+ digits, then a colon, a closing parenthesis, or a period that no digit
11
+ follows, so a version such as 2.0 passes.
12
+ - It holds a backtick, the mark of a code-formatted name.
13
+
14
+ A call with no string subject passes, so a status-only TaskUpdate keeps working.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import sys
20
+ from pathlib import Path
21
+
22
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
23
+ if hooks_root_directory not in sys.path:
24
+ sys.path.insert(0, hooks_root_directory)
25
+
26
+ from hooks_constants.hook_block_logger import log_hook_block
27
+ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
28
+ from hooks_constants.task_subject_outcome_constants import (
29
+ ALL_SUBJECT_TOOL_NAMES,
30
+ ALLOW_EXIT_CODE,
31
+ BLOCK_EXIT_CODE,
32
+ CODE_SPAN_MARKER,
33
+ CODE_SPAN_MESSAGE,
34
+ GATE_EVENT_NAME,
35
+ PROCEDURE_STEP_MESSAGE,
36
+ PROCEDURE_STEP_PREFIX_PATTERN,
37
+ RETRY_INSTRUCTION,
38
+ TASK_SUBJECT_KEY,
39
+ TODO_CONTENT_KEY,
40
+ TODO_WRITE_TOOL_NAME,
41
+ TODOS_KEY,
42
+ TOOL_INPUT_KEY,
43
+ TOOL_NAME_KEY,
44
+ )
45
+
46
+
47
+ def task_subject_violation(subject: str) -> str | None:
48
+ """Return the message for the marker a task subject carries, or None when it reads as an outcome.
49
+
50
+ >>> task_subject_violation("PR 2347 merged with checks green") is None
51
+ True
52
+ >>> task_subject_violation("Feature 3: Write the checkpoint").startswith("The task subject")
53
+ True
54
+
55
+ Args:
56
+ subject: The wording the task list would show the user.
57
+
58
+ Returns:
59
+ The message for the marker, or None.
60
+ """
61
+ if PROCEDURE_STEP_PREFIX_PATTERN.match(subject):
62
+ return PROCEDURE_STEP_MESSAGE.format(subject=subject)
63
+ if CODE_SPAN_MARKER in subject:
64
+ return CODE_SPAN_MESSAGE.format(subject=subject)
65
+ return None
66
+
67
+
68
+ def _subjects_in_call(tool_name: str, all_tool_input_fields: dict[str, object]) -> list[str]:
69
+ if tool_name in ALL_SUBJECT_TOOL_NAMES:
70
+ subject = all_tool_input_fields.get(TASK_SUBJECT_KEY)
71
+ return [subject] if isinstance(subject, str) else []
72
+ if tool_name != TODO_WRITE_TOOL_NAME:
73
+ return []
74
+ all_todo_entries = all_tool_input_fields.get(TODOS_KEY)
75
+ if not isinstance(all_todo_entries, list):
76
+ return []
77
+ return [
78
+ each_entry[TODO_CONTENT_KEY]
79
+ for each_entry in all_todo_entries
80
+ if isinstance(each_entry, dict) and isinstance(each_entry.get(TODO_CONTENT_KEY), str)
81
+ ]
82
+
83
+
84
+ def main() -> int:
85
+ hook_input = read_hook_input_dictionary_from_stdin()
86
+ if hook_input is None:
87
+ return ALLOW_EXIT_CODE
88
+ tool_name = hook_input.get(TOOL_NAME_KEY)
89
+ tool_input = hook_input.get(TOOL_INPUT_KEY)
90
+ if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
91
+ return ALLOW_EXIT_CODE
92
+ for each_subject in _subjects_in_call(tool_name, tool_input):
93
+ violation = task_subject_violation(each_subject)
94
+ if violation is None:
95
+ continue
96
+ block_reason = violation + RETRY_INSTRUCTION
97
+ log_hook_block(
98
+ Path(__file__).name,
99
+ GATE_EVENT_NAME,
100
+ block_reason,
101
+ tool_name=tool_name,
102
+ offending_input_preview=each_subject,
103
+ )
104
+ sys.stderr.write(block_reason)
105
+ return BLOCK_EXIT_CODE
106
+ return ALLOW_EXIT_CODE
107
+
108
+
109
+ if __name__ == "__main__":
110
+ sys.exit(main())
@@ -5,13 +5,16 @@ import pytest
5
5
 
6
6
  from open_tasks_transcript import (
7
7
  TaskItem,
8
+ advanced_items,
8
9
  claude_prompt_text,
10
+ codex_plan_items,
9
11
  codex_prompt_text,
10
12
  is_assistant_record,
11
13
  is_codex_read_call,
12
14
  is_codex_work_call,
13
15
  is_read_tool_name,
14
16
  is_work_tool_name,
17
+ merged_todo_items,
15
18
  parsed_object,
16
19
  replayed_transcript,
17
20
  send_call_file_paths,
@@ -194,6 +197,35 @@ def test_should_parse_text_nested_past_the_recursion_limit_as_no_object() -> Non
194
197
  assert parsed_object('{"a": ' * 100_000) is None
195
198
 
196
199
 
200
+ def test_should_replay_the_readable_records_and_skip_unreadable_transcripts(tmp_path: Path) -> None:
201
+ prompt_record = {"type": "user", "message": {"role": "user", "content": "Export the APKs"}}
202
+ transcript_path = tmp_path / "mixed.jsonl"
203
+ transcript_path.write_bytes(b"not json\n[1, 2]\n\xff\xfe\n" + json.dumps(prompt_record).encode("utf-8") + b"\n")
204
+ assert replayed_transcript(str(transcript_path)).turn_prompt_text == "Export the APKs"
205
+ missing_replay = replayed_transcript(str(tmp_path / "missing.jsonl"))
206
+ assert missing_replay.items() is None
207
+ assert missing_replay.turn_prompt_text == ""
208
+ assert replayed_transcript(None).items() is None
209
+
210
+
211
+ def test_should_merge_todo_updates_by_id_advance_the_plan_and_read_a_codex_plan() -> None:
212
+ all_earlier_items = [TaskItem("1", "Write the gate", "in_progress"), TaskItem("2", "Open the PR", "pending")]
213
+ all_merged_items = merged_todo_items(all_earlier_items, [{"id": "1", "status": "completed"}, {"id": "3", "content": "Tag it"}])
214
+ assert all_merged_items == [
215
+ TaskItem("1", "Write the gate", "completed"),
216
+ TaskItem("2", "Open the PR", "pending"),
217
+ TaskItem("3", "Tag it", ""),
218
+ ]
219
+ assert advanced_items(all_earlier_items) == [
220
+ TaskItem("1", "Write the gate", "completed"),
221
+ TaskItem("2", "Open the PR", "in_progress"),
222
+ ]
223
+ plan_arguments = json.dumps({"plan": [{"step": "Port parser", "status": "completed"}, "skip", {"step": "Run tests"}]})
224
+ plan_record = {"type": "response_item", "payload": {"type": "function_call", "name": "update_plan", "arguments": plan_arguments}}
225
+ assert codex_plan_items(plan_record) == [TaskItem("1", "Port parser", "completed"), TaskItem("2", "Run tests", "")]
226
+ assert codex_plan_items({"type": "response_item", "payload": {"type": "function_call", "name": "shell"}}) is None
227
+
228
+
197
229
  def ccd_plan_record(all_plan_input: dict[str, object], record_type: str = "assistant") -> dict[str, object]:
198
230
  tool_use = {"type": "tool_use", "id": "p1", "name": "mcp__ccd_turn__update_plan", "input": all_plan_input}
199
231
  return {"type": record_type, "timestamp": "2026-01-01T00:00:00.000Z", "message": {"content": [tool_use]}}