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.
- package/bin/ever-registered-hooks.mjs +1 -0
- package/docs/agents-guidance/asks.md +4 -0
- package/hooks/blocking/open_tasks_transcript.py +15 -186
- package/hooks/blocking/open_tasks_transcript_records.py +211 -0
- package/hooks/blocking/task_subject_outcome_gate.py +110 -0
- package/hooks/blocking/test_open_tasks_transcript.py +32 -0
- package/hooks/blocking/test_open_tasks_transcript_records.py +174 -0
- package/hooks/blocking/test_task_subject_outcome_gate.py +129 -0
- package/hooks/blocking/test_turn_review_gate.py +19 -0
- package/hooks/features/conduct-gates.md +3 -0
- package/hooks/features/lifecycle-cleanup.md +1 -1
- package/hooks/hooks.json +5 -0
- package/hooks/hooks_constants/task_subject_outcome_constants.py +37 -0
- package/hooks/lifecycle/nested_project_hooks.py +1 -148
- package/hooks/lifecycle/nested_project_hooks_discovery.py +168 -0
- package/hooks/lifecycle/test_nested_project_hooks.py +41 -0
- package/hooks/lifecycle/test_nested_project_hooks_discovery.py +164 -0
- package/hooks/validation/post_tool_use_dispatcher.py +27 -8
- package/hooks/validation/test_post_tool_use_dispatcher.py +51 -0
- package/package.json +1 -1
- package/scripts/policy_lint/adapter_configuration.py +5 -0
- package/scripts/policy_lint/config/constants.py +1 -0
- package/scripts/tests/test_adapter_configuration.py +8 -0
|
@@ -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]}}
|