claude-dev-env 8.120.0 → 8.122.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 (42) hide show
  1. package/bin/ever-registered-hooks.mjs +2 -0
  2. package/docs/rule-guides/question-presentation.md +4 -0
  3. package/hooks/advisory/auto_mode_denial_quick_fix.py +275 -27
  4. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_cases.json +3475 -0
  5. package/hooks/advisory/auto_mode_rule_flow_eval/auto_mode_rule_flow_runner.py +849 -0
  6. package/hooks/advisory/auto_mode_rule_flow_eval/stub_allow_hook.py +20 -0
  7. package/hooks/advisory/auto_mode_rule_flow_eval/stub_hold_hook.py +54 -0
  8. package/hooks/advisory/auto_mode_rule_flow_eval/test_auto_mode_rule_flow_runner.py +143 -0
  9. package/hooks/advisory/test_auto_mode_denial_quick_fix.py +533 -9
  10. package/hooks/auto_mode_question_transcript.py +215 -0
  11. package/hooks/auto_mode_refusal_ledger.py +481 -0
  12. package/hooks/auto_mode_refusal_ledger_files.py +336 -0
  13. package/hooks/auto_mode_rule_steps.py +177 -0
  14. package/hooks/blocking/auto_mode_refusal_stop_gate.py +384 -0
  15. package/hooks/blocking/sent_file_question_detector.py +340 -0
  16. package/hooks/blocking/sent_file_question_gate.py +307 -0
  17. package/hooks/blocking/sent_file_scan.py +209 -0
  18. package/hooks/blocking/test_auto_mode_refusal_stop_gate.py +484 -0
  19. package/hooks/blocking/test_sent_file_question_detector.py +68 -0
  20. package/hooks/blocking/test_sent_file_question_gate.py +688 -0
  21. package/hooks/blocking/test_sent_file_scan.py +71 -0
  22. package/hooks/blocking/test_user_step_wording.py +46 -0
  23. package/hooks/blocking/user_step_wording.py +113 -15
  24. package/hooks/features/README.md +1 -1
  25. package/hooks/features/conduct-gates.md +3 -0
  26. package/hooks/features/session-context.md +5 -2
  27. package/hooks/hooks.json +15 -0
  28. package/hooks/hooks_constants/auto_mode_denial_quick_fix_constants.py +51 -3
  29. package/hooks/hooks_constants/auto_mode_refusal_ledger_constants.py +85 -0
  30. package/hooks/hooks_constants/auto_mode_refusal_stop_gate_constants.py +80 -0
  31. package/hooks/hooks_constants/auto_mode_rule_flow_runner_constants.py +225 -0
  32. package/hooks/hooks_constants/auto_mode_rule_steps_constants.py +82 -0
  33. package/hooks/hooks_constants/sent_file_question_gate_constants.py +261 -0
  34. package/hooks/hooks_constants/user_step_wording_constants.py +4 -0
  35. package/hooks/test_auto_mode_question_transcript.py +113 -0
  36. package/hooks/test_auto_mode_refusal_ledger.py +398 -0
  37. package/hooks/test_auto_mode_refusal_ledger_files.py +155 -0
  38. package/hooks/test_auto_mode_rule_steps.py +210 -0
  39. package/package.json +1 -1
  40. package/scripts/policy_lint/adapter_configuration.py +10 -0
  41. package/scripts/policy_lint/config/constants.py +2 -0
  42. package/scripts/tests/test_adapter_configuration.py +16 -0
@@ -0,0 +1,340 @@
1
+ """Find a question for the user in the text of a sent file or page.
2
+
3
+ The sent file question gate reads a file and calls ``question_for_user`` on
4
+ its text. The rules for what counts as a question live here, and the gate
5
+ module keeps the tool call, the file read, and the refusal::
6
+
7
+ "Checks passed. Should I merge it?" -> "Should I merge it?"
8
+ "## How do I install it?\n\nRun the installer." -> None
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import sys
14
+ from pathlib import Path
15
+
16
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
17
+ if hooks_root_directory not in sys.path:
18
+ sys.path.insert(0, hooks_root_directory)
19
+ blocking_directory = str(Path(__file__).resolve().parent)
20
+ if blocking_directory not in sys.path:
21
+ sys.path.insert(0, blocking_directory)
22
+
23
+ from final_reply_gate import prose_paragraphs_with_code_as
24
+ from hooks_constants.sent_file_question_gate_constants import (
25
+ SPACE,
26
+ MAXIMUM_SENTENCE_CHARACTERS,
27
+ REPLY_REQUEST_PATTERN,
28
+ CHECK_BLOCK_WORD_PATTERN,
29
+ CHOICE_COMMAND_PATTERN,
30
+ LABEL_CHOICE_PATTERN,
31
+ YES_OR_NO_REQUEST_PATTERN,
32
+ TASK_BOX_MARK,
33
+ REPLY_OPTION_PATTERN,
34
+ SENTENCE_EDGE_CHARACTERS,
35
+ SENTENCE_EDGE_JOIN,
36
+ TASK_CHECK_PATTERN,
37
+ WRITER_VOICE_HEADING_PATTERN,
38
+ ALL_BOLD_MARKS,
39
+ ALL_FULL_WIDTH_QUESTION_MARKS,
40
+ ALL_INDENTED_CODE_PREFIXES,
41
+ ALL_QUOTED_QUESTION_ENDINGS,
42
+ ANSWER_LABEL_PATTERN,
43
+ ANSWER_OPENER_PATTERN,
44
+ BOLD_MARK_COUNT,
45
+ EMPHASIS_CHARACTERS,
46
+ EMPHASIS_PATTERN,
47
+ HEADING_CLOSE_MARKS,
48
+ HEADING_MARK,
49
+ HEADING_OPENER_PATTERN,
50
+ LABEL_COLON,
51
+ LINE_BREAK,
52
+ LIST_MARKER_PATTERN,
53
+ MAXIMUM_CHOICE_WORDS,
54
+ OPEN_ASK_PATTERN,
55
+ QUESTION_LABEL_PATTERN,
56
+ QUESTION_MARK,
57
+ QUESTION_SECTION_PATTERN,
58
+ QUOTED_SPAN_PATTERN,
59
+ READER_ADDRESS_PATTERN,
60
+ READER_CHOICE_PATTERN,
61
+ READER_WISH_PATTERN,
62
+ REQUEST_OPENER_PATTERN,
63
+ RESPONSE_PROMPT_PATTERN,
64
+ SENTENCE_PATTERN,
65
+ SPACE_RUN_PATTERN,
66
+ TABLE_CELL_SEPARATOR,
67
+ TABLE_DIVIDER_CELL_PATTERN,
68
+ TABLE_ROW_PATTERN,
69
+ TASK_BOX_PATTERN,
70
+ TRAILING_CLOSERS,
71
+ TRAILING_MARKS,
72
+ UNIT_START_PATTERN,
73
+ WH_CHOICE_PATTERN,
74
+ )
75
+ from hooks_constants.user_step_wording_constants import (
76
+ CODE_SPAN_STAND_IN,
77
+ )
78
+ from user_step_wording import html_text_blocks
79
+
80
+
81
+ def _plain_words(text: str) -> str:
82
+ return SPACE_RUN_PATTERN.sub(" ", EMPHASIS_PATTERN.sub("", text)).strip()
83
+
84
+
85
+ def _is_question(sentence: str) -> bool:
86
+ if not sentence.rstrip(TRAILING_MARKS).endswith(QUESTION_MARK):
87
+ return False
88
+ return not sentence.rstrip(TRAILING_CLOSERS).endswith(ALL_QUOTED_QUESTION_ENDINGS)
89
+
90
+
91
+ def _is_short_choice(sentence: str) -> bool:
92
+ return (
93
+ READER_CHOICE_PATTERN.search(sentence) is not None
94
+ and len(sentence.split()) <= MAXIMUM_CHOICE_WORDS
95
+ )
96
+
97
+
98
+ def _asks_the_reader(sentence: str) -> bool:
99
+ if not _is_question(sentence):
100
+ return False
101
+ return (
102
+ _is_short_choice(sentence)
103
+ or READER_ADDRESS_PATTERN.search(sentence) is not None
104
+ or REQUEST_OPENER_PATTERN.match(sentence) is not None
105
+ or OPEN_ASK_PATTERN.match(sentence) is not None
106
+ or WH_CHOICE_PATTERN.match(sentence) is not None
107
+ )
108
+
109
+
110
+ def _is_wish_ask(sentence: str) -> bool:
111
+ return (
112
+ READER_ADDRESS_PATTERN.search(sentence) is not None
113
+ and READER_WISH_PATTERN.search(sentence) is not None
114
+ )
115
+
116
+
117
+ def _sentence_edges(sentence: str) -> str:
118
+ if len(sentence) <= MAXIMUM_SENTENCE_CHARACTERS:
119
+ return sentence
120
+ return (
121
+ sentence[:SENTENCE_EDGE_CHARACTERS]
122
+ + SENTENCE_EDGE_JOIN
123
+ + sentence[-SENTENCE_EDGE_CHARACTERS:]
124
+ )
125
+
126
+
127
+ def _is_reply_request(sentence: str) -> bool:
128
+ if REPLY_REQUEST_PATTERN.match(sentence) is not None:
129
+ return True
130
+ if YES_OR_NO_REQUEST_PATTERN.search(sentence) is not None:
131
+ return True
132
+ if CHOICE_COMMAND_PATTERN.match(sentence) is None or sentence.endswith(LABEL_COLON):
133
+ return False
134
+ return (
135
+ REPLY_OPTION_PATTERN.search(sentence) is not None
136
+ or LABEL_CHOICE_PATTERN.search(sentence) is not None
137
+ )
138
+
139
+
140
+ def _is_check(sentence: str) -> bool:
141
+ return (
142
+ TASK_CHECK_PATTERN.match(sentence) is not None
143
+ and CHECK_BLOCK_WORD_PATTERN.search(sentence) is None
144
+ and not _is_wish_ask(sentence)
145
+ and not _is_short_choice(sentence)
146
+ )
147
+
148
+
149
+ def _is_answered(sentence: str, next_sentence: str) -> bool:
150
+ if ANSWER_OPENER_PATTERN.match(next_sentence) is not None:
151
+ return True
152
+ is_open_ask = not _is_wish_ask(sentence) and REQUEST_OPENER_PATTERN.match(sentence) is None
153
+ return (
154
+ is_open_ask
155
+ and bool(next_sentence)
156
+ and not _is_question(next_sentence)
157
+ and RESPONSE_PROMPT_PATTERN.match(next_sentence) is None
158
+ )
159
+
160
+
161
+ def _text_units(block_text: str) -> list[str]:
162
+ all_unit_lines: list[list[str]] = []
163
+ for each_line in block_text.split(LINE_BREAK):
164
+ if not each_line.strip():
165
+ continue
166
+ if all_unit_lines and UNIT_START_PATTERN.match(each_line) is None:
167
+ all_unit_lines[-1].append(each_line.strip())
168
+ continue
169
+ all_unit_lines.append([each_line.strip()])
170
+ return [SPACE.join(each_lines) for each_lines in all_unit_lines]
171
+
172
+
173
+ def _heading_text(unit_text: str) -> str | None:
174
+ opener = HEADING_OPENER_PATTERN.match(unit_text)
175
+ if opener is not None:
176
+ return unit_text[opener.end() :].strip().rstrip(HEADING_CLOSE_MARKS).strip()
177
+ label_text = unit_text.rstrip()
178
+ if label_text.endswith(LABEL_COLON):
179
+ label_text = label_text[: -len(LABEL_COLON)].rstrip()
180
+ for each_mark in ALL_BOLD_MARKS:
181
+ is_wrapped = (
182
+ len(label_text) > BOLD_MARK_COUNT * len(each_mark)
183
+ and label_text.startswith(each_mark)
184
+ and label_text.endswith(each_mark)
185
+ and label_text[len(each_mark)] not in EMPHASIS_CHARACTERS
186
+ )
187
+ if is_wrapped:
188
+ return label_text[len(each_mark) : -len(each_mark)]
189
+ return None
190
+
191
+
192
+ def _heading_question(heading_text: str) -> str | None:
193
+ section_name = _plain_words(heading_text).rstrip(LABEL_COLON).strip()
194
+ return section_name if QUESTION_SECTION_PATTERN.fullmatch(section_name) else None
195
+
196
+
197
+ def _table_question(row_text: str) -> str | None:
198
+ all_cells = [
199
+ _plain_words(each_cell)
200
+ for each_cell in row_text.strip().strip(TABLE_CELL_SEPARATOR).split(TABLE_CELL_SEPARATOR)
201
+ ]
202
+ if all(TABLE_DIVIDER_CELL_PATTERN.match(each_cell) for each_cell in all_cells):
203
+ return None
204
+ filled_cells = [each_cell for each_cell in all_cells if each_cell]
205
+ if filled_cells and _asks_the_reader(filled_cells[-1]):
206
+ return filled_cells[-1]
207
+ return None
208
+
209
+
210
+ def _sentence_question(unit_text: str, is_checklist_item: bool) -> str | None:
211
+ unquoted_text = QUOTED_SPAN_PATTERN.sub(CODE_SPAN_STAND_IN, unit_text)
212
+ all_sentences = [
213
+ _sentence_edges(_plain_words(each_match.group()))
214
+ for each_match in SENTENCE_PATTERN.finditer(unquoted_text)
215
+ ]
216
+ for each_index, each_sentence in enumerate(all_sentences):
217
+ if _is_reply_request(each_sentence):
218
+ return each_sentence
219
+ next_sentence = all_sentences[each_index + 1] if each_index + 1 < len(all_sentences) else ""
220
+ if is_checklist_item and _is_check(each_sentence):
221
+ continue
222
+ if _asks_the_reader(each_sentence) and not _is_answered(each_sentence, next_sentence):
223
+ return each_sentence
224
+ return None
225
+
226
+
227
+ def _is_question_list_item(unit_text: str | None) -> bool:
228
+ return (
229
+ unit_text is not None
230
+ and LIST_MARKER_PATTERN.match(unit_text) is not None
231
+ and _is_question(unit_text)
232
+ )
233
+
234
+
235
+ def _is_checklist_item(unit_text: str, earlier_unit: str | None, later_unit: str | None) -> bool:
236
+ if LIST_MARKER_PATTERN.match(unit_text) is None:
237
+ return False
238
+ return (
239
+ TASK_BOX_PATTERN.match(unit_text) is not None
240
+ or _is_question_list_item(earlier_unit)
241
+ or _is_question_list_item(later_unit)
242
+ )
243
+
244
+
245
+ def _asking_heading(heading_text: str, later_unit: str | None) -> str | None:
246
+ heading_words = _sentence_edges(_plain_words(heading_text))
247
+ if _is_question(heading_words) and WRITER_VOICE_HEADING_PATTERN.search(heading_words):
248
+ return heading_words
249
+ if not _asks_the_reader(heading_words):
250
+ return None
251
+ is_answered_below = (
252
+ later_unit is not None
253
+ and _heading_text(later_unit) is None
254
+ and LIST_MARKER_PATTERN.match(later_unit) is None
255
+ )
256
+ return None if is_answered_below else heading_words
257
+
258
+
259
+ def _unit_question(
260
+ unit_text: str, earlier_unit: str | None, later_unit: str | None, has_later_answer: bool
261
+ ) -> str | None:
262
+ heading_text = _heading_text(unit_text)
263
+ if heading_text is not None:
264
+ return _heading_question(heading_text) or _asking_heading(heading_text, later_unit)
265
+ if TABLE_ROW_PATTERN.match(unit_text):
266
+ return _table_question(unit_text)
267
+ if ANSWER_LABEL_PATTERN.match(unit_text):
268
+ return None
269
+ question_label = QUESTION_LABEL_PATTERN.match(unit_text)
270
+ if question_label is not None:
271
+ if has_later_answer:
272
+ return None
273
+ return _sentence_question(unit_text[question_label.end() :], is_checklist_item=False)
274
+ return _sentence_question(
275
+ LIST_MARKER_PATTERN.sub("", unit_text, count=1),
276
+ _is_checklist_item(unit_text, earlier_unit, later_unit),
277
+ )
278
+
279
+
280
+ def _without_indented_code(file_text: str) -> str:
281
+ all_kept_lines: list[str] = []
282
+ is_after_blank_line = True
283
+ is_in_code_block = False
284
+ for each_line in file_text.split(LINE_BREAK):
285
+ if not each_line.strip():
286
+ all_kept_lines.append(each_line)
287
+ is_after_blank_line = True
288
+ continue
289
+ is_indented = each_line.startswith(ALL_INDENTED_CODE_PREFIXES)
290
+ is_in_code_block = is_indented and (is_in_code_block or is_after_blank_line)
291
+ all_kept_lines.append("" if is_in_code_block else each_line)
292
+ is_after_blank_line = False
293
+ return LINE_BREAK.join(all_kept_lines)
294
+
295
+
296
+ def question_for_user(file_text: str, is_html: bool) -> str | None:
297
+ """Return the first question the file asks the user, or None.
298
+
299
+ >>> question_for_user("Checks passed. Should I merge it?", is_html=False)
300
+ 'Should I merge it?'
301
+ >>> question_for_user("## How do I install it?\\n\\nRun the installer.", is_html=False) is None
302
+ True
303
+
304
+ Args:
305
+ file_text: The text of a Markdown or plain text file, or an HTML page source.
306
+ is_html: True for an HTML page, read through its shown text.
307
+
308
+ Returns:
309
+ The question sentence or section heading, as plain words, or None.
310
+ """
311
+ for each_mark in ALL_FULL_WIDTH_QUESTION_MARKS:
312
+ file_text = file_text.replace(each_mark, QUESTION_MARK)
313
+ if is_html:
314
+ all_blocks = html_text_blocks(file_text, HEADING_MARK, task_box_mark=TASK_BOX_MARK)
315
+ else:
316
+ all_blocks = prose_paragraphs_with_code_as(
317
+ _without_indented_code(file_text), CODE_SPAN_STAND_IN
318
+ )
319
+ all_units = [each_unit for each_block in all_blocks for each_unit in _text_units(each_block)]
320
+ all_later_answer_flags = _later_answer_flags(all_units)
321
+ for each_index, each_unit in enumerate(all_units):
322
+ earlier_unit = all_units[each_index - 1] if each_index else None
323
+ later_unit = all_units[each_index + 1] if each_index + 1 < len(all_units) else None
324
+ question = _unit_question(
325
+ each_unit, earlier_unit, later_unit, all_later_answer_flags[each_index]
326
+ )
327
+ if question is not None:
328
+ return question
329
+ return None
330
+
331
+
332
+ def _later_answer_flags(all_units: list[str]) -> list[bool]:
333
+ all_flags = [False] * len(all_units)
334
+ has_answer_after = False
335
+ for each_index in range(len(all_units) - 1, -1, -1):
336
+ all_flags[each_index] = has_answer_after
337
+ has_answer_after = has_answer_after or bool(
338
+ ANSWER_LABEL_PATTERN.match(all_units[each_index])
339
+ )
340
+ return all_flags
@@ -0,0 +1,307 @@
1
+ #!/usr/bin/env python3
2
+ """PreToolUse hook that keeps questions for the user out of the files and pages a session sends.
3
+
4
+ The user answers a question through the question tool's card. A question
5
+ inside a sent file or a published page gets no card, and the user may never
6
+ see it. So the gate reads each Markdown, text, or HTML file a SendUserFile
7
+ call sends, and the page an Artifact publish sends, and denies the call when
8
+ the file asks the user something::
9
+
10
+ deny: ## Questions for you (a heading that opens a question section)
11
+ deny: Should I archive the old branches? (a request for a go-ahead)
12
+ deny: Do you want the cache cleared first? (a question that names the reader)
13
+ deny: Keep it merged, or revert it? (a choice)
14
+ allow: ## How do I install it? (a heading: the answer sits below it)
15
+ allow: Does it retry? No. It fails at once. (the text answers its own question)
16
+ allow: Can I use it offline? After a sync. (a frequently asked question and its answer)
17
+ allow: Do you need admin? Only to install. (the same, worded to the reader)
18
+ allow: > Should we ship this? (a quote)
19
+ allow: an Artifact publish that declares db or artifact, such as option cards that save the answer
20
+
21
+ A question line is a sentence that ends with a question mark (or a full-width
22
+ one) and names the reader (you, your), opens with a request (should I, want
23
+ me, okay to, proceed, merge, thoughts, are we good, would it make sense,
24
+ ...), opens with "can I", "could we", or "may I", asks which or what works
25
+ best or should be done ("What release date works best?"), or offers a choice
26
+ with "or" in ten words or fewer. A sentence that asks for a reply on its own
27
+ ("Let me know which you prefer.", "Please advise which one to apply.", "Tell
28
+ me which.", "Send me your pick.") counts too, as does a sentence that opens
29
+ with reply, answer, respond, choose, pick, select, or decide and offers yes
30
+ or no, one of two, three, four, both, these, those, or them, or a choice
31
+ between labels that are one letter, one digit, or "option" and a word
32
+ ("Choose A or B."), unless it ends with a colon. Reply, answer, respond,
33
+ choose, or pick after "please" or a comma, a few words before "yes or no",
34
+ counts too ("Please answer yes or no.", "When it ends, reply with yes or
35
+ no."). "Select one or more
36
+ archives." and "Choose Color or Image." are steps and pass. A list marker
37
+ and a task box ("- [ ]", or a checkbox ``input`` in a page) before it are
38
+ skipped. A checklist item, a list item with a task box or next to another
39
+ question item, passes only when it asks whether the reader did a piece of
40
+ work: it opens with "Did you" or "Have you" and a verb such as saved, ran,
41
+ tested, pushed, committed, updated, added, removed, checked, read,
42
+ installed, restarted, closed, or filled in ("Did you run the tests?"), and
43
+ holds none of ok, fine, good, signed off, approve, happy, ready, want,
44
+ prefer, decide, agree, go ahead, ship, merge, delete, confirm, choice, or
45
+ choose.
46
+
47
+ Quotes, fenced and indented code, and preformatted text are not read. A
48
+ heading, a ``summary`` label, or a ``dt`` label is refused when it opens a
49
+ question or decision section, such as "Open questions", "Decisions needed
50
+ from you", or "Need your input", or when it asks the reader something and no
51
+ paragraph follows to answer it ("## Which works best?" at the end of the
52
+ file or above a list of options). A question heading in the writer's or the
53
+ reader-addressed voice is refused whatever follows it: it holds should I,
54
+ should we, shall I, shall we, do you, would you, will you, can you, want me,
55
+ your, or prefer ("## What should I do next?"). "## Can I run it offline?",
56
+ "## Why does this exist?" and "## How does it work?" pass with an answer
57
+ paragraph below them.
58
+
59
+ A question the next sentence answers with "Yes," "No." and the like passes;
60
+ "Yes or no." and "No rush." are no answers. A question that asks for no
61
+ wish or go-ahead passes when a statement follows it in the same paragraph or
62
+ list item, unless that statement asks for a reply ("Reply yes", "Let me
63
+ know"). A wish or go-ahead names the reader with a word such as want,
64
+ prefer, like, approve, think, or me, or opens with a request. A "Q:" line
65
+ with an "A:" line below it, in the same block or a later one, and a table
66
+ cell with an answer cell after it, pass.
67
+
68
+ A file over 256 KB is read through its first and last 128 KB, and the
69
+ refusal, or a system message when the gate lets the call run, says so. A file
70
+ that holds a NUL byte or is not UTF-8, and a file the gate cannot read, pass.
71
+ The refusal quotes at most 160 characters of the question. A sentence or
72
+ heading over 2,000 characters is read through its first and last 400
73
+ characters. The read runs on a worker thread with a 4 s
74
+ budget. When the HTML parser does not finish in that time, a second read
75
+ strips the tags in one pass with no parser and applies the same rules, with
76
+ another 4 s. Only when that read also runs out does the call run, with a
77
+ system message that the files went unchecked. Both budgets stay under the
78
+ hook's 10 s timeout.
79
+ """
80
+
81
+ from __future__ import annotations
82
+
83
+ import json
84
+ import sys
85
+ import threading
86
+ from pathlib import Path
87
+
88
+ hooks_root_directory = str(Path(__file__).resolve().parent.parent)
89
+ if hooks_root_directory not in sys.path:
90
+ sys.path.insert(0, hooks_root_directory)
91
+ blocking_directory = str(Path(__file__).resolve().parent)
92
+ if blocking_directory not in sys.path:
93
+ sys.path.insert(0, blocking_directory)
94
+
95
+ from hooks_constants.hook_block_logger import log_hook_block
96
+ from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
97
+ from hooks_constants.sent_file_question_gate_constants import (
98
+ PLAIN_READ_BUDGET_SECONDS,
99
+ PARSED_READ_BUDGET_SECONDS,
100
+ ALLOW_EXIT_CODE,
101
+ ALL_ANSWER_SAVING_CAPABILITIES,
102
+ ALL_SKIPPED_PUBLISH_INPUT_KEYS,
103
+ ARTIFACT_ACTION_INPUT_KEY,
104
+ ARTIFACT_CAPABILITIES_INPUT_KEY,
105
+ ARTIFACT_FILE_PATH_INPUT_KEY,
106
+ ARTIFACT_PUBLISH_ACTION,
107
+ ARTIFACT_TOOL_NAME,
108
+ BLOCK_EXIT_CODE,
109
+ CWD_KEY,
110
+ FILE_PATH_SEPARATOR,
111
+ GATE_EVENT_NAME,
112
+ MAXIMUM_QUOTED_CHARACTERS,
113
+ PARTIAL_READ_MESSAGE,
114
+ PARTIAL_READ_NOTE,
115
+ QUESTION_FOUND_MESSAGE,
116
+ QUOTE_CUT_MARK,
117
+ SCAN_TIMEOUT_MESSAGE,
118
+ SYSTEM_MESSAGE_KEY,
119
+ TOOL_INPUT_KEY,
120
+ TOOL_NAME_KEY,
121
+ )
122
+ from open_tasks_transcript_records import send_call_file_paths
123
+ from sent_file_question_detector import question_for_user
124
+ from sent_file_scan import plain_page_text, sent_file_is_partly_read, sent_file_scan_text
125
+ from user_step_wording import is_html_file_path
126
+
127
+
128
+ def _short_quote(question: str) -> str:
129
+ if len(question) <= MAXIMUM_QUOTED_CHARACTERS:
130
+ return question
131
+ return question[: MAXIMUM_QUOTED_CHARACTERS - len(QUOTE_CUT_MARK)].rstrip() + QUOTE_CUT_MARK
132
+
133
+
134
+ def _saves_the_answer(all_tool_input_fields: dict[str, object]) -> bool:
135
+ all_capabilities = all_tool_input_fields.get(ARTIFACT_CAPABILITIES_INPUT_KEY)
136
+ if not isinstance(all_capabilities, dict):
137
+ return False
138
+ return not ALL_ANSWER_SAVING_CAPABILITIES.isdisjoint(all_capabilities)
139
+
140
+
141
+ def _published_page_paths(all_tool_input_fields: dict[str, object]) -> list[str]:
142
+ if (
143
+ all_tool_input_fields.get(ARTIFACT_ACTION_INPUT_KEY, ARTIFACT_PUBLISH_ACTION)
144
+ != ARTIFACT_PUBLISH_ACTION
145
+ ):
146
+ return []
147
+ if any(all_tool_input_fields.get(each_key) for each_key in ALL_SKIPPED_PUBLISH_INPUT_KEYS):
148
+ return []
149
+ if _saves_the_answer(all_tool_input_fields):
150
+ return []
151
+ page_path = all_tool_input_fields.get(ARTIFACT_FILE_PATH_INPUT_KEY)
152
+ return [page_path] if isinstance(page_path, str) else []
153
+
154
+
155
+ def sent_file_paths(tool_name: str, all_tool_input_fields: dict[str, object]) -> list[str]:
156
+ """Return the paths of the files a SendUserFile call or an Artifact page publish hands the user.
157
+
158
+ >>> sent_file_paths("SendUserFile", {"files": ["a.md", "b.html"]})
159
+ ['a.md', 'b.html']
160
+ >>> sent_file_paths("Artifact", {"file_path": "page.html", "capabilities": {"db": {}}})
161
+ []
162
+ >>> sent_file_paths("Artifact", {"file_path": "page.html", "capabilities": {"sample": {}}})
163
+ ['page.html']
164
+
165
+ Args:
166
+ tool_name: The tool the session called.
167
+ all_tool_input_fields: The tool input.
168
+
169
+ Returns:
170
+ The paths in call order. An Artifact call that reads, lists, uploads an
171
+ asset, or starts from a type gives none, and so does a publish that
172
+ declares a capability that saves an answer: db, artifact, or self.
173
+ """
174
+ if tool_name == ARTIFACT_TOOL_NAME:
175
+ return _published_page_paths(all_tool_input_fields)
176
+ return send_call_file_paths(tool_name, all_tool_input_fields)
177
+
178
+
179
+ def _file_question(file_path_text: str, file_text: str, is_plain_page_read: bool) -> str | None:
180
+ if is_plain_page_read and is_html_file_path(file_path_text):
181
+ return question_for_user(plain_page_text(file_text), is_html=False)
182
+ return question_for_user(file_text, is_html_file_path(file_path_text))
183
+
184
+
185
+ def _sent_file_findings(
186
+ all_file_paths: list[str], working_directory: object, is_plain_page_read: bool
187
+ ) -> list[tuple[str, str | None, bool]]:
188
+ all_findings: list[tuple[str, str | None, bool]] = []
189
+ for each_path in all_file_paths:
190
+ file_text = sent_file_scan_text(each_path, working_directory)
191
+ if file_text is None:
192
+ continue
193
+ question = _file_question(each_path, file_text, is_plain_page_read)
194
+ is_partly_read = sent_file_is_partly_read(each_path, working_directory)
195
+ all_findings.append((each_path, question, is_partly_read))
196
+ if question is not None:
197
+ break
198
+ return all_findings
199
+
200
+
201
+ def findings_within_budget(
202
+ all_file_paths: list[str],
203
+ working_directory: object,
204
+ budget_seconds: float,
205
+ *,
206
+ is_plain_page_read: bool,
207
+ ) -> list[tuple[str, str | None, bool]] | None:
208
+ """Read the sent files on a worker thread, and give up when the budget runs out.
209
+
210
+ ::
211
+
212
+ two short files -> [("a.md", None, False), ("b.md", "Should I merge it?", False)]
213
+ a page the parser chews -> None, after budget_seconds
214
+
215
+ The hook command has a 10 s timeout, and a hook that times out lets the
216
+ call run with no word to anyone. A budget below that timeout lets the gate
217
+ say so itself.
218
+
219
+ Args:
220
+ all_file_paths: The paths the call sends.
221
+ working_directory: The session's ``cwd`` from the hook payload.
222
+ budget_seconds: How long the read may take.
223
+ is_plain_page_read: True to read an HTML page through
224
+ ``plain_page_text``, with no HTML parser.
225
+
226
+ Returns:
227
+ One (path, question or None, read only in part) entry per readable
228
+ file, up to the first question, or None when the read did not finish.
229
+ """
230
+ all_results: list[list[tuple[str, str | None, bool]]] = []
231
+ worker = threading.Thread(
232
+ target=lambda: all_results.append(
233
+ _sent_file_findings(all_file_paths, working_directory, is_plain_page_read)
234
+ ),
235
+ daemon=True,
236
+ )
237
+ worker.start()
238
+ worker.join(budget_seconds)
239
+ return all_results[0] if all_results else None
240
+
241
+
242
+ def _write_system_message(message_text: str) -> None:
243
+ sys.stdout.write(json.dumps({SYSTEM_MESSAGE_KEY: message_text}))
244
+
245
+
246
+ def _reported_findings(all_findings: list[tuple[str, str | None, bool]], tool_name: str) -> int:
247
+ for each_path, each_question, each_is_partly_read in all_findings:
248
+ if each_question is None:
249
+ continue
250
+ block_reason = QUESTION_FOUND_MESSAGE.format(
251
+ file_path=each_path, question=_short_quote(each_question)
252
+ )
253
+ if each_is_partly_read:
254
+ block_reason += PARTIAL_READ_NOTE.format(file_path=each_path)
255
+ log_hook_block(
256
+ Path(__file__).name,
257
+ GATE_EVENT_NAME,
258
+ block_reason,
259
+ tool_name=tool_name,
260
+ offending_input_preview=each_path,
261
+ )
262
+ sys.stderr.write(block_reason)
263
+ return BLOCK_EXIT_CODE
264
+ all_partly_read_paths = [
265
+ each_path
266
+ for each_path, _each_question, each_is_partly_read in all_findings
267
+ if each_is_partly_read
268
+ ]
269
+ if all_partly_read_paths:
270
+ _write_system_message(
271
+ PARTIAL_READ_MESSAGE.format(file_paths=FILE_PATH_SEPARATOR.join(all_partly_read_paths))
272
+ )
273
+ return ALLOW_EXIT_CODE
274
+
275
+
276
+ def main() -> int:
277
+ hook_input = read_hook_input_dictionary_from_stdin()
278
+ if hook_input is None:
279
+ return ALLOW_EXIT_CODE
280
+ tool_name = hook_input.get(TOOL_NAME_KEY)
281
+ tool_input = hook_input.get(TOOL_INPUT_KEY)
282
+ if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
283
+ return ALLOW_EXIT_CODE
284
+ all_file_paths = sent_file_paths(tool_name, tool_input)
285
+ if not all_file_paths:
286
+ return ALLOW_EXIT_CODE
287
+ working_directory = hook_input.get(CWD_KEY)
288
+ all_findings = findings_within_budget(
289
+ all_file_paths, working_directory, PARSED_READ_BUDGET_SECONDS, is_plain_page_read=False
290
+ )
291
+ if all_findings is None:
292
+ all_findings = findings_within_budget(
293
+ all_file_paths, working_directory, PLAIN_READ_BUDGET_SECONDS, is_plain_page_read=True
294
+ )
295
+ if all_findings is None:
296
+ _write_system_message(
297
+ SCAN_TIMEOUT_MESSAGE.format(
298
+ file_paths=FILE_PATH_SEPARATOR.join(all_file_paths),
299
+ budget_seconds=PARSED_READ_BUDGET_SECONDS + PLAIN_READ_BUDGET_SECONDS,
300
+ )
301
+ )
302
+ return ALLOW_EXIT_CODE
303
+ return _reported_findings(all_findings, tool_name)
304
+
305
+
306
+ if __name__ == "__main__":
307
+ sys.exit(main())