claude-dev-env 8.117.5 → 8.118.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.
@@ -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
@@ -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())
@@ -0,0 +1,129 @@
1
+ import io
2
+ import json
3
+ from pathlib import Path
4
+
5
+ import pytest
6
+
7
+ import task_subject_outcome_gate
8
+
9
+
10
+ def run_gate(
11
+ monkeypatch: pytest.MonkeyPatch,
12
+ capsys: pytest.CaptureFixture[str],
13
+ tool_name: str,
14
+ tool_input: object,
15
+ ) -> tuple[int, str]:
16
+ hook_input = {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": tool_input}
17
+ monkeypatch.setattr(
18
+ "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
19
+ )
20
+ exit_code = task_subject_outcome_gate.main()
21
+ return exit_code, capsys.readouterr().err
22
+
23
+
24
+ @pytest.fixture(autouse=True)
25
+ def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
26
+ monkeypatch.setenv("HOME", str(tmp_path))
27
+ monkeypatch.setenv("USERPROFILE", str(tmp_path))
28
+
29
+
30
+ @pytest.mark.parametrize("tool_name", ["TaskCreate", "TaskUpdate"])
31
+ @pytest.mark.parametrize(
32
+ "subject",
33
+ [
34
+ "Task names in the list read as outcomes",
35
+ "PR 2347 merged with checks green",
36
+ "PR 12: checks green",
37
+ "Issue 7: closed with the fix linked",
38
+ "Merge PR #2347 once review is clean",
39
+ "Feature flag removed from the settings page",
40
+ "Step notes turn off when the user asks",
41
+ "Phase 2.0 released to all users",
42
+ ],
43
+ )
44
+ def test_should_allow_a_plain_outcome_subject(
45
+ monkeypatch: pytest.MonkeyPatch,
46
+ capsys: pytest.CaptureFixture[str],
47
+ tool_name: str,
48
+ subject: str,
49
+ ) -> None:
50
+ assert run_gate(monkeypatch, capsys, tool_name, {"subject": subject}) == (0, "")
51
+
52
+
53
+ @pytest.mark.parametrize(
54
+ "subject",
55
+ [
56
+ "Feature 1: Investigate the affected subsystem",
57
+ "Feature 3: Write the throughput checkpoint",
58
+ "Feature 6-8: Rebase into small ordered commits, run Opening a PR",
59
+ "Step 3: run the tests",
60
+ "phase 2) migrate callers",
61
+ "Bug fix 4. Reproduce first",
62
+ "Bug fix 5: Reproduce first",
63
+ ],
64
+ )
65
+ def test_should_deny_a_subject_that_starts_with_a_procedure_step_label(
66
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], subject: str
67
+ ) -> None:
68
+ exit_code, stderr_text = run_gate(monkeypatch, capsys, "TaskCreate", {"subject": subject})
69
+ assert exit_code == 2
70
+ assert "procedure step label" in stderr_text
71
+ assert "by its outcome in the user's words" in stderr_text
72
+ assert "private checklist" in stderr_text
73
+
74
+
75
+ def test_should_deny_a_subject_with_a_code_formatted_name(
76
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
77
+ ) -> None:
78
+ exit_code, stderr_text = run_gate(
79
+ monkeypatch, capsys, "TaskUpdate", {"taskId": "3", "subject": "Run `how` over the hooks"}
80
+ )
81
+ assert exit_code == 2
82
+ assert "code-formatted name" in stderr_text
83
+
84
+
85
+ def test_should_deny_a_todo_write_item_that_carries_a_marker(
86
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
87
+ ) -> None:
88
+ all_todos = [
89
+ {"content": "Hook refuses procedure step names", "status": "completed"},
90
+ {"content": "Step 2: push the branch", "status": "pending"},
91
+ ]
92
+ exit_code, stderr_text = run_gate(monkeypatch, capsys, "TodoWrite", {"todos": all_todos})
93
+ assert exit_code == 2
94
+ assert "Step 2: push the branch" in stderr_text
95
+
96
+
97
+ def test_should_allow_todo_write_items_that_read_as_outcomes(
98
+ monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
99
+ ) -> None:
100
+ all_todos = [{"content": "Hook refuses procedure step names", "status": "in_progress"}]
101
+ assert run_gate(monkeypatch, capsys, "TodoWrite", {"todos": all_todos}) == (0, "")
102
+
103
+
104
+ @pytest.mark.parametrize(
105
+ ("tool_name", "tool_input"),
106
+ [
107
+ ("TaskUpdate", {"taskId": "3", "status": "completed"}),
108
+ ("TaskCreate", "Step 1: not a dictionary"),
109
+ ("Bash", {"subject": "Step 1: run"}),
110
+ ("TodoWrite", {"todos": "Step 1: run"}),
111
+ ],
112
+ )
113
+ def test_should_leave_other_tools_and_schemas_alone(
114
+ monkeypatch: pytest.MonkeyPatch,
115
+ capsys: pytest.CaptureFixture[str],
116
+ tool_name: str,
117
+ tool_input: object,
118
+ ) -> None:
119
+ assert run_gate(monkeypatch, capsys, tool_name, tool_input) == (0, "")
120
+
121
+
122
+ def test_task_subject_violation_should_return_none_for_an_outcome() -> None:
123
+ assert task_subject_outcome_gate.task_subject_violation("Hook refuses step names") is None
124
+
125
+
126
+ def test_task_subject_violation_should_name_the_backtick_marker() -> None:
127
+ violation = task_subject_outcome_gate.task_subject_violation("Fix `gate.py`")
128
+ assert violation is not None
129
+ assert "code-formatted name" in violation
@@ -12,6 +12,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
12
12
  - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
13
13
  - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
14
14
  - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
15
+ - `blocking/task_subject_outcome_gate.py` denies a TaskCreate or TaskUpdate subject, or a TodoWrite item, that starts with a procedure step label (step, phase, stage, part, feature, bug fix, refactoring, or playbook, then a one- or two-digit number or range, then `:`, `)`, or a `.` that no digit follows) or holds a backtick. The reason says to name the item by its outcome in the user's words and keep procedure steps in a private checklist file. A status-only TaskUpdate passes.
15
16
  - `blocking/task_subject_length_gate.py` denies a `TaskCreate` or `TaskUpdate` whose `subject` is over 80 characters, and a `TodoWrite` whose list holds an item `content` over 80 characters, naming the first such item. The reason gives the length and the limit and says to start with who acts (Me, You, or Handed off), say what is left, and put detail in the description.
16
17
  - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
17
18
  - `blocking/wakeup_cap_gate.py` keeps a self-wakeup inside the 1-hour prompt cache. A wake over the step-down (57 minutes for `send_later` and Routines, 3480 seconds for `ScheduleWakeup`) and at most 60 minutes away runs with its delay rewritten to the step-down. A wake over 60 minutes away, or a cron with more than 57 minutes between wakes, is denied with a reason that says to stack wakes under the cap. A Routine that starts a fresh session on each firing passes.
@@ -36,6 +37,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
36
37
  - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
37
38
  - `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
38
39
  - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
40
+ - `blocking/task_subject_outcome_gate.py` runs on `PreToolUse`, matcher `TaskCreate|TaskUpdate|TodoWrite`, timeout `10` seconds in `hooks.json`, after the length gate in the same group. Like the length gate, it runs in Claude Code only.
39
41
  - `blocking/task_subject_length_gate.py` runs on `PreToolUse`, matcher `TaskCreate|TaskUpdate|TodoWrite`, timeout `10` seconds in `hooks.json`. It runs in Claude Code only: the installer gives Codex only the PreToolUse group whose matcher is `multi_agent_v1__spawn_agent`, and gives Cursor only the hooks `bin/install-constants.mjs` names.
40
42
  - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
41
43
  - `blocking/question_brief_gate.py` runs on `PreToolUse`, matcher `AskUserQuestion`, timeout `10` seconds in `hooks.json`. Its transcript poll stops at 3 seconds.
@@ -65,6 +67,7 @@ Preconditions:
65
67
  - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
66
68
  - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
67
69
  - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
70
+ - **Procedure step names.** Input is a TaskCreate subject `Feature 3: Write the throughput checkpoint`, a TaskUpdate subject with a backtick, and a TodoWrite item `Step 2: push the branch`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_task_subject_outcome_gate.py -q`. The adjacent test observes a denial for each; `PR 12: checks green`, `PR 2347 merged with checks green`, and a status-only TaskUpdate pass.
68
71
  - **Task subject.** Input is a `TaskCreate` call whose subject is a 229-character status sentence, then three short subjects that start with Me, You, and Handed off. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_task_subject_length_gate.py -q`. The adjacent test observes a denial that gives the status sentence's length and the limit, the short ones passing, 80 characters passing and 81 denied, a status-only `TaskUpdate` passing, and a `TodoWrite` denial that names its long item.
69
72
  - **First title.** Input is a `UserPromptSubmit` payload with a work prompt, after a transcript that lists the title tool and holds no title call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_tracking_nudge.py -q`. The adjacent test observes one note that names the tool and `⏳ <name>`, exit 0 and empty stderr. A second ask and an ask after a compaction get no such note. A session without the title tool, and a title that shows the hourglass, get no title note.
70
73
  - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
package/hooks/hooks.json CHANGED
@@ -236,6 +236,11 @@
236
236
  "type": "command",
237
237
  "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/task_subject_length_gate.py",
238
238
  "timeout": 10
239
+ },
240
+ {
241
+ "type": "command",
242
+ "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/task_subject_outcome_gate.py",
243
+ "timeout": 10
239
244
  }
240
245
  ]
241
246
  },
@@ -0,0 +1,37 @@
1
+ """Constants for task_subject_outcome_gate.py."""
2
+
3
+ import re
4
+
5
+ TOOL_NAME_KEY = "tool_name"
6
+ TOOL_INPUT_KEY = "tool_input"
7
+ GATE_EVENT_NAME = "PreToolUse"
8
+ ALLOW_EXIT_CODE = 0
9
+ BLOCK_EXIT_CODE = 2
10
+
11
+ TASK_CREATE_TOOL_NAME = "TaskCreate"
12
+ TASK_UPDATE_TOOL_NAME = "TaskUpdate"
13
+ TODO_WRITE_TOOL_NAME = "TodoWrite"
14
+ ALL_SUBJECT_TOOL_NAMES = frozenset({TASK_CREATE_TOOL_NAME, TASK_UPDATE_TOOL_NAME})
15
+ TASK_SUBJECT_KEY = "subject"
16
+ TODOS_KEY = "todos"
17
+ TODO_CONTENT_KEY = "content"
18
+
19
+ PROCEDURE_STEP_PREFIX_PATTERN = re.compile(
20
+ r"^\s*(?:step|phase|stage|part|feature|bug\s+fix|refactoring|playbook)"
21
+ r"\s*\d{1,2}(?:\s*[-–]\s*\d{1,2})?\s*(?:[:)]|\.(?!\d))",
22
+ re.IGNORECASE,
23
+ )
24
+ CODE_SPAN_MARKER = "`"
25
+
26
+ PROCEDURE_STEP_MESSAGE = (
27
+ "The task subject '{subject}' starts with a procedure step label such as 'Step 3:' or"
28
+ " 'Feature 6-8:'."
29
+ )
30
+ CODE_SPAN_MESSAGE = "The task subject '{subject}' holds a code-formatted name in backticks."
31
+ RETRY_INSTRUCTION = (
32
+ " The user follows the task list to see where the work stands and what is left."
33
+ " Name the item by its outcome in the user's words, such as"
34
+ " 'Task names in the list read as outcomes'."
35
+ " Keep playbook steps, skill names, and other procedure steps in a private checklist"
36
+ " file such as todo.md in the work folder, and call the tool again."
37
+ )
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "claude-dev-env",
3
- "version": "8.117.5",
3
+ "version": "8.118.0",
4
4
  "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
5
5
  "type": "module",
6
6
  "bin": {
@@ -134,6 +134,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
134
134
  hooks/blocking/issue_close_handoff_gate.py -> exempt
135
135
  hooks/blocking/verify_before_acting.py -> exempt
136
136
  hooks/blocking/session_title_format_gate.py -> exempt
137
+ hooks/blocking/task_subject_outcome_gate.py -> exempt
137
138
  hooks/blocking/artifact_dark_mode_gate.py -> exempt
138
139
  hooks/blocking/send_user_file_worktree_root_gate.py -> exempt
139
140
  hooks/blocking/question_brief_gate.py -> exempt
@@ -176,6 +177,10 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
176
177
  The session title format gate denies a malformed title. It decides the
177
178
  shape of a title and no code or safety policy.
178
179
 
180
+ The task subject gate denies a task list subject that starts with a
181
+ procedure step label or holds a code-formatted name. It decides the
182
+ wording the user reads and no code or safety policy.
183
+
179
184
  The artifact page gate denies a page publish whose text is unreadable in
180
185
  dark mode. It decides how a page renders and no code or safety policy.
181
186
 
@@ -71,6 +71,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
71
71
  "blocking/issue_close_handoff_gate.py",
72
72
  "blocking/verify_before_acting.py",
73
73
  "blocking/session_title_format_gate.py",
74
+ "blocking/task_subject_outcome_gate.py",
74
75
  "blocking/image_read_size_gate.py",
75
76
  "blocking/artifact_dark_mode_gate.py",
76
77
  "blocking/send_user_file_worktree_root_gate.py",
@@ -130,6 +130,14 @@ def test_new_session_title_gate_registration_is_clean(tmp_path: Path) -> None:
130
130
  assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
131
131
 
132
132
 
133
+ def test_new_task_subject_outcome_gate_registration_is_clean(tmp_path: Path) -> None:
134
+ current_document = _hook_document(
135
+ ["hooks/blocking/task_subject_outcome_gate.py"],
136
+ '{"hooks": {}}',
137
+ )
138
+ assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
139
+
140
+
133
141
  def test_new_task_subject_gate_registration_is_clean(tmp_path: Path) -> None:
134
142
  current_document = _hook_document(
135
143
  ["hooks/blocking/task_subject_length_gate.py"],