claude-dev-env 8.87.0 → 8.88.0

package/hooks/blocking/test_open_tasks_stop_gate.py

@@ -0,0 +1,297 @@
+import io
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+import open_tasks_stop_gate
+
+GATE_PATH = Path(open_tasks_stop_gate.__file__)
+SESSION_ID = "s-123"
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+    monkeypatch.delenv("CLAUDE_CODE_TASK_LIST_ID", raising=False)
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    reply_text: str,
+    transcript_path: Path | None = None,
+) -> tuple[int, str]:
+    hook_input: dict[str, object] = {
+        "hook_event_name": "Stop",
+        "session_id": SESSION_ID,
+        "stop_hook_active": False,
+        "last_assistant_message": reply_text,
+    }
+    if transcript_path is not None:
+        hook_input["transcript_path"] = str(transcript_path)
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = open_tasks_stop_gate.main()
+    return exit_code, capsys.readouterr().out
+
+
+def write_task_store(home_directory: Path, all_tasks: list[dict[str, str]]) -> None:
+    task_directory = home_directory / ".claude" / "tasks" / SESSION_ID
+    task_directory.mkdir(parents=True)
+    for each_task in all_tasks:
+        (task_directory / f"{each_task['id']}.json").write_text(json.dumps(each_task), encoding="utf-8")
+
+
+def write_todo_transcript(transcript_path: Path, all_todos: list[dict[str, str]]) -> Path:
+    tool_use = {"type": "tool_use", "id": "t1", "name": "TodoWrite", "input": {"todos": all_todos}}
+    transcript_path.write_text(
+        json.dumps({"type": "assistant", "message": {"content": [tool_use]}}), encoding="utf-8"
+    )
+    return transcript_path
+
+
+def test_should_block_when_a_pending_task_is_not_reported(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    write_task_store(tmp_path, [{"id": "1", "subject": "Rotate the deploy key", "status": "pending"}])
+    exit_code, stdout_text = run_gate(monkeypatch, capsys, "All done.")
+    decision = json.loads(stdout_text)
+    assert exit_code == 0
+    assert decision["decision"] == "block"
+    assert "Rotate the deploy key" in decision["reason"]
+
+
+def test_should_allow_when_every_open_task_is_reported_as_blocked_or_open(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    write_task_store(
+        tmp_path,
+        [
+            {"id": "1", "subject": "Rotate the deploy key", "status": "pending"},
+            {"id": "2", "subject": "Wait on checks", "status": "in_progress"},
+            {"id": "3", "subject": "Write tests", "status": "completed"},
+        ],
+    )
+    reply_text = "Tests written.\nBlocked: Rotate the deploy key - the owner approves the secret\n- Open: #2 - checks running"
+    assert run_gate(monkeypatch, capsys, reply_text) == (0, "")
+
+
+def test_should_block_when_the_item_is_only_mentioned_in_prose(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    write_task_store(tmp_path, [{"id": "1", "subject": "Rotate the deploy key", "status": "pending"}])
+    _, stdout_text = run_gate(monkeypatch, capsys, "I will rotate the deploy key later.")
+    assert json.loads(stdout_text)["decision"] == "block"
+
+
+def test_should_allow_when_every_task_is_completed(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    write_task_store(tmp_path, [{"id": "1", "subject": "Rotate the deploy key", "status": "completed"}])
+    assert run_gate(monkeypatch, capsys, "Done.") == (0, "")
+
+
+def test_should_read_todowrite_from_the_transcript_when_no_task_store_exists(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_todo_transcript(
+        tmp_path / "s.jsonl",
+        [{"content": "Ship the fix", "status": "in_progress"}, {"content": "Lint", "status": "completed"}],
+    )
+    _, stdout_text = run_gate(monkeypatch, capsys, "Done.", transcript_path)
+    reason_text = json.loads(stdout_text)["reason"]
+    assert "Ship the fix" in reason_text
+    assert "Lint" not in reason_text
+
+
+def test_should_replay_taskcreate_and_taskupdate_from_the_transcript(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_records = [
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "c1", "name": "TaskCreate", "input": {"subject": "Alpha"}}]}},
+        {"type": "user", "message": {"content": [{"type": "tool_result", "tool_use_id": "c1", "content": "Task #1 created successfully: Alpha"}]}},
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "c2", "name": "TaskCreate", "input": {"subject": "Beta"}}]}},
+        {"type": "user", "message": {"content": [{"type": "tool_result", "tool_use_id": "c2", "content": "Task #2 created successfully: Beta"}]}},
+        {"type": "assistant", "message": {"content": [{"type": "tool_use", "id": "u1", "name": "TaskUpdate", "input": {"taskId": "1", "status": "completed"}}]}},
+    ]
+    transcript_path = tmp_path / "s.jsonl"
+    transcript_path.write_text("\n".join(json.dumps(each) for each in transcript_records), encoding="utf-8")
+    _, stdout_text = run_gate(monkeypatch, capsys, "Done.", transcript_path)
+    reason_text = json.loads(stdout_text)["reason"]
+    assert "Beta" in reason_text
+    assert "Alpha" not in reason_text
+
+
+def test_should_read_codex_update_plan_from_the_rollout(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    plan_arguments = json.dumps({"plan": [{"step": "Port the hook", "status": "pending"}]})
+    rollout_record = {"type": "response_item", "payload": {"type": "function_call", "name": "update_plan", "arguments": plan_arguments}}
+    transcript_path = tmp_path / "rollout.jsonl"
+    transcript_path.write_text(json.dumps(rollout_record), encoding="utf-8")
+    _, stdout_text = run_gate(monkeypatch, capsys, "Done.", transcript_path)
+    assert "Port the hook" in json.loads(stdout_text)["reason"]
+
+
+def test_should_allow_a_session_with_no_task_list(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert run_gate(monkeypatch, capsys, "Done.") == (0, "")
+
+
+def test_should_allow_malformed_stdin(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"not json")))
+    assert (open_tasks_stop_gate.main(), capsys.readouterr().out) == (0, "")
+
+
+def test_should_block_through_a_subprocess_with_the_documented_contract(tmp_path: Path) -> None:
+    write_task_store(tmp_path, [{"id": "1", "subject": "Rotate the deploy key", "status": "pending"}])
+    hook_input = {"hook_event_name": "Stop", "session_id": SESSION_ID, "last_assistant_message": "Done."}
+    completed_process = subprocess.run(
+        [sys.executable, str(GATE_PATH)],
+        input=json.dumps(hook_input),
+        capture_output=True,
+        text=True,
+        env={"HOME": str(tmp_path), "USERPROFILE": str(tmp_path), "PATH": ""},
+        check=False,
+    )
+    assert completed_process.returncode == 0
+    assert json.loads(completed_process.stdout)["decision"] == "block"
+
+
+def write_cursor_transcript(transcript_path: Path, all_records: list[dict[str, object]]) -> Path:
+    transcript_path.write_text("\n".join(json.dumps(each_record) for each_record in all_records), encoding="utf-8")
+    return transcript_path
+
+
+def cursor_todo_record(all_todos: list[dict[str, str]], is_merge: bool, reply_text: str) -> dict[str, object]:
+    tool_use = {"type": "tool_use", "name": "TodoWrite", "input": {"todos": all_todos, "merge": is_merge}}
+    return {"role": "assistant", "message": {"content": [{"type": "text", "text": reply_text}, tool_use]}}
+
+
+def run_cursor_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    transcript_path: Path,
+    stop_status: str = "completed",
+    loop_count: int = 0,
+) -> dict[str, str]:
+    hook_input = {
+        "hook_event_name": "stop",
+        "conversation_id": "c-1",
+        "status": stop_status,
+        "loop_count": loop_count,
+        "transcript_path": str(transcript_path),
+    }
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8"))))
+    open_tasks_stop_gate.main()
+    printed_output = capsys.readouterr().out
+    return json.loads(printed_output) if printed_output else {}
+
+
+def test_should_send_a_cursor_followup_when_a_merged_todo_stays_pending(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_first_todos = [
+        {"id": "1", "content": "write hello.txt", "status": "in_progress"},
+        {"id": "2", "content": "rotate the deploy key", "status": "pending"},
+    ]
+    transcript_path = write_cursor_transcript(
+        tmp_path / "cursor.jsonl",
+        [
+            cursor_todo_record(all_first_todos, False, "Starting."),
+            cursor_todo_record([{"id": "1", "status": "completed"}], True, "Done."),
+        ],
+    )
+    block_output = run_cursor_gate(monkeypatch, capsys, transcript_path)
+    assert "rotate the deploy key" in block_output["followup_message"]
+    assert "write hello.txt" not in block_output["followup_message"]
+    assert block_output["decision"] == "block"
+
+
+@pytest.mark.parametrize("stop_status", ["aborted", "error"])
+def test_should_allow_a_cursor_stop_the_user_aborted_or_that_errored(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path, stop_status: str
+) -> None:
+    all_todos = [{"id": "2", "content": "rotate the deploy key", "status": "pending"}]
+    transcript_path = write_cursor_transcript(
+        tmp_path / "cursor.jsonl", [cursor_todo_record(all_todos, False, "Stopping.")]
+    )
+    assert run_cursor_gate(monkeypatch, capsys, transcript_path, stop_status) == {}
+
+
+def test_should_allow_cursor_when_the_last_assistant_text_reports_the_item(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_todos = [{"id": "2", "content": "rotate the deploy key", "status": "pending"}]
+    transcript_path = write_cursor_transcript(
+        tmp_path / "cursor.jsonl",
+        [
+            cursor_todo_record(all_todos, False, "Working."),
+            {"role": "assistant", "message": {"content": [
+                {"type": "text", "text": "Blocked: rotate the deploy key - the owner must approve the org secret"}
+            ]}},
+        ],
+    )
+    assert run_cursor_gate(monkeypatch, capsys, transcript_path) == {}
+
+
+def test_should_leave_claude_block_output_without_a_followup_message(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    transcript_path = write_todo_transcript(
+        tmp_path / "t.jsonl", [{"content": "rotate the deploy key", "status": "pending"}]
+    )
+    _, printed_output = run_gate(monkeypatch, capsys, "Done.", transcript_path)
+    assert set(json.loads(printed_output)) == {"decision", "reason"}
+
+
+def cursor_dynamic_todo_record(all_todos: list[dict[str, str]], is_merge: bool) -> dict[str, object]:
+    tool_use = {
+        "type": "tool_use",
+        "name": "CallDynamicTool",
+        "input": {"namespace": "cursor", "toolName": "TodoWrite", "arguments": {"merge": is_merge, "todos": all_todos}},
+    }
+    return {"role": "assistant", "message": {"content": [tool_use]}}
+
+
+def test_should_read_todos_the_cursor_cli_writes_through_call_dynamic_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_first_todos = [
+        {"id": "1", "content": "write hello.txt", "status": "in_progress"},
+        {"id": "2", "content": "rotate the deploy key", "status": "pending"},
+    ]
+    all_merged_todos = [
+        {"id": "1", "content": "write hello.txt", "status": "completed"},
+        {"id": "2", "content": "rotate the deploy key", "status": "pending"},
+    ]
+    transcript_path = write_cursor_transcript(
+        tmp_path / "cursor.jsonl",
+        [
+            cursor_dynamic_todo_record(all_first_todos, False),
+            cursor_dynamic_todo_record(all_merged_todos, True),
+            {"role": "assistant", "message": {"content": [{"type": "text", "text": "Done."}]}},
+            {"type": "turn_ended", "status": "success"},
+        ],
+    )
+    block_output = run_cursor_gate(monkeypatch, capsys, transcript_path)
+    assert "rotate the deploy key" in block_output["followup_message"]
+    assert "write hello.txt" not in block_output["followup_message"]
+
+
+def test_should_allow_a_cursor_stop_after_five_followups(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], tmp_path: Path
+) -> None:
+    all_todos = [{"id": "2", "content": "rotate the deploy key", "status": "pending"}]
+    transcript_path = write_cursor_transcript(tmp_path / "cursor.jsonl", [cursor_todo_record(all_todos, False, "Done.")])
+    assert "rotate the deploy key" in run_cursor_gate(monkeypatch, capsys, transcript_path, loop_count=4)["followup_message"]
+    assert run_cursor_gate(monkeypatch, capsys, transcript_path, loop_count=5) == {}

package/hooks/blocking/test_open_tasks_transcript.py

@@ -0,0 +1,54 @@
+import json
+from pathlib import Path
+
+from open_tasks_transcript import TaskItem, parsed_object, replayed_transcript, unwrapped_tool_call
+
+
+def write_transcript(transcript_path: Path, all_records: list[dict[str, object]]) -> Path:
+    transcript_path.write_text("\n".join(json.dumps(each_record) for each_record in all_records), encoding="utf-8")
+    return transcript_path
+
+
+def dynamic_todo_record(all_todos: list[dict[str, str]], is_merge: bool) -> dict[str, object]:
+    tool_use = {
+        "type": "tool_use",
+        "name": "CallDynamicTool",
+        "input": {"namespace": "cursor", "toolName": "TodoWrite", "arguments": {"merge": is_merge, "todos": all_todos}},
+    }
+    return {"role": "assistant", "message": {"content": [tool_use]}}
+
+
+def test_should_unwrap_a_call_dynamic_tool_todo_write_call() -> None:
+    all_arguments = {"merge": False, "todos": []}
+    wrapped_input = {"namespace": "cursor", "toolName": "TodoWrite", "arguments": all_arguments}
+    assert unwrapped_tool_call("CallDynamicTool", wrapped_input) == ("TodoWrite", all_arguments)
+    assert unwrapped_tool_call("Read", wrapped_input) == ("Read", wrapped_input)
+    assert unwrapped_tool_call("CallDynamicTool", {"toolName": "TodoWrite"}) == ("CallDynamicTool", {"toolName": "TodoWrite"})
+
+
+def test_should_replay_cursor_dynamic_todo_writes_and_the_last_reply(tmp_path: Path) -> None:
+    all_first_todos = [
+        {"id": "1", "content": "write hello.txt", "status": "in_progress"},
+        {"id": "2", "content": "rotate the deploy key", "status": "pending"},
+    ]
+    transcript_path = write_transcript(
+        tmp_path / "cursor.jsonl",
+        [
+            dynamic_todo_record(all_first_todos, False),
+            dynamic_todo_record([{"id": "1", "content": "write hello.txt", "status": "completed"}], True),
+            {"role": "assistant", "message": {"content": [{"type": "text", "text": "Done."}]}},
+            {"type": "turn_ended", "status": "success"},
+        ],
+    )
+    replay = replayed_transcript(str(transcript_path))
+    assert replay.items() == [
+        TaskItem("1", "write hello.txt", "completed"),
+        TaskItem("2", "rotate the deploy key", "pending"),
+    ]
+    assert replay.last_assistant_text == "Done."
+
+
+def test_should_parse_only_json_objects() -> None:
+    assert parsed_object('{"a": 1}') == {"a": 1}
+    assert parsed_object("[1]") is None
+    assert parsed_object("not json") is None

package/hooks/features/conduct-gates.md

@@ -6,6 +6,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on.
 - `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with.
+- `blocking/open_tasks_stop_gate.py` holds the end of a turn while the session task list has items that are neither completed nor named on a `Blocked:` or `Open:` line of the closing reply. `blocking/open_tasks_transcript.py` rebuilds the task list and the last reply from the transcript for it.
 - The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies the first claim about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
 - `blocking/chat_reply_gate.py` runs the `reply_length_gate.py` reply checks on a plain chat reply, which is no tool call. On `UserPromptSubmit` it adds the reply rules as `additionalContext`. On `MessageDisplay` it holds each streamed batch until the message ends. A message that passes shows whole. A message that fails shows as a draft from `claude -p` on Haiku that passes the same checks, and the original shows when two drafts fail. The draft changes only the text on screen, so the next `UserPromptSubmit` tells the agent the text the user saw, and `SessionEnd` deletes the stored draft. The [reply arena harness](https://github.com/jl-cmd-projects/claude-dev-env/tree/160349b90f627ea542fc6bc7b2b7f86dcbf98b73/tests/reply_arena) ran the comparison that chose this display path.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
@@ -23,6 +24,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 
 - `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision|AskUserQuestion|mcp__hearthbot__post_widget`, timeout `10` seconds in `hooks.json`.
 - `blocking/final_reply_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
+- `blocking/open_tasks_stop_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`. The installer also registers it on Codex `Stop` and as a native Cursor `stop` entry in `~/.cursor/hooks.json`, where a block also returns `followup_message`. A Cursor stop with status `aborted` or `error` passes. A Cursor stop whose `loop_count` is 5 or more passes, because a copy Cursor imports from `~/.claude/settings.json` has no follow-up limit.
 - The claim judge runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision`, timeout `30` seconds in `hooks.json`.
 - `blocking/chat_reply_gate.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds, on `MessageDisplay`, timeout `100` seconds, and on `SessionEnd`, timeout `3` seconds, in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
@@ -44,6 +46,7 @@ Preconditions:
 
 - **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
 - **Final reply.** Input is a closing reply that says "My guess is one to two hours." or cites a run no tool result shows. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_final_reply_gate.py -q`. The adjacent test observes a `block` decision that quotes the sentence or the citation; a reply that cites a run a tool result shows passes.
+- **Open tasks.** Input is a session whose task list still has "rotate the deploy key" pending and a closing reply of "Done.". Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_open_tasks_stop_gate.py -q`. The adjacent test observes a `block` decision that names the item; a reply line `Blocked: rotate the deploy key - <what the user must give>` passes.
 - **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Fact with no source: ...`. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
 - **Chat reply.** Input is a `MessageDisplay` event whose message holds four sentences, the same message split over two batches, and a `UserPromptSubmit` event. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_chat_reply_gate.py -q`. The adjacent test observes the drafter's text in `displayContent`, an empty first batch, no output for three sentences, the original after two failed drafts, the shown draft in the next `additionalContext`, and the stored draft deleted at session end.
 - **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.

package/hooks/hooks.json

@@ -379,6 +379,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/final_reply_gate.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_tasks_stop_gate.py",
+            "timeout": 10
           }
         ]
       }

package/hooks/hooks_constants/cursor_agents_guidance_constants.py

@@ -0,0 +1,6 @@
+"""Constants for cursor_agents_guidance.py, the Cursor SessionStart hook."""
+
+GUIDANCE_PATH_ARGUMENT_INDEX = 1
+CURSOR_CONTEXT_KEY = "additional_context"
+UTF8_ENCODING = "utf-8"
+EMPTY_OUTPUT = "{}"

package/hooks/hooks_constants/open_tasks_stop_gate_constants.py

@@ -0,0 +1,72 @@
+"""Constants for the open tasks Stop gate."""
+
+HOOK_EVENT_NAME = "Stop"
+SESSION_ID_KEY = "session_id"
+TRANSCRIPT_PATH_KEY = "transcript_path"
+LAST_ASSISTANT_MESSAGE_KEY = "last_assistant_message"
+DECISION_KEY = "decision"
+BLOCK_DECISION = "block"
+REASON_KEY = "reason"
+ALLOW_EXIT_CODE = 0
+UTF8_ENCODING = "utf-8"
+WORD_SEPARATOR = " "
+TASK_LIST_ID_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_TASK_LIST_ID"
+CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE = "CLAUDE_CONFIG_DIR"
+CLAUDE_HOME_DIRECTORY_NAME = ".claude"
+TASKS_DIRECTORY_NAME = "tasks"
+TASK_FILE_GLOB = "*.json"
+TASK_ID_KEY = "id"
+TASK_SUBJECT_KEY = "subject"
+TASK_STATUS_KEY = "status"
+PENDING_STATUS = "pending"
+INCOMPLETE_STATUSES = frozenset({PENDING_STATUS, "in_progress"})
+RECORD_TYPE_KEY = "type"
+MESSAGE_KEY = "message"
+CONTENT_KEY = "content"
+TEXT_KEY = "text"
+TOOL_NAME_KEY = "name"
+TOOL_INPUT_KEY = "input"
+TOOL_USE_ID_KEY = "tool_use_id"
+TODOS_KEY = "todos"
+TODO_CONTENT_KEY = "content"
+TODO_ID_KEY = "id"
+TODO_MERGE_KEY = "merge"
+ROLE_KEY = "role"
+ASSISTANT_ROLE = "assistant"
+CURSOR_CONVERSATION_ID_KEY = "conversation_id"
+CURSOR_FOLLOWUP_MESSAGE_KEY = "followup_message"
+CURSOR_STATUS_KEY = "status"
+CURSOR_COMPLETED_STATUS = "completed"
+CURSOR_LOOP_COUNT_KEY = "loop_count"
+CURSOR_FOLLOWUP_LIMIT = 5
+REPLY_TEXT_SEPARATOR = "\n"
+TASK_UPDATE_ID_KEY = "taskId"
+TODO_WRITE_TOOL_NAME = "TodoWrite"
+DYNAMIC_TOOL_CALL_NAME = "CallDynamicTool"
+DYNAMIC_TOOL_NAME_KEY = "toolName"
+DYNAMIC_TOOL_ARGUMENTS_KEY = "arguments"
+TASK_CREATE_TOOL_NAME = "TaskCreate"
+TASK_UPDATE_TOOL_NAME = "TaskUpdate"
+TOOL_USE_BLOCK_TYPE = "tool_use"
+TOOL_RESULT_BLOCK_TYPE = "tool_result"
+CODEX_RESPONSE_ITEM_TYPE = "response_item"
+CODEX_FUNCTION_CALL_TYPE = "function_call"
+CODEX_PAYLOAD_KEY = "payload"
+CODEX_ARGUMENTS_KEY = "arguments"
+CODEX_PLAN_TOOL_NAME = "update_plan"
+CODEX_PLAN_KEY = "plan"
+CODEX_STEP_KEY = "step"
+FIRST_ITEM_NUMBER = 1
+TASK_CREATED_PATTERN = r"Task #(\d+) created"
+CREATED_TASK_ID_GROUP_INDEX = 1
+REPORT_LINE_PATTERN = r"^\s*(?:[-*]\s*)?(open|blocked)\b\s*[:\-]?\s*(.*)$"
+REPORTED_TEXT_GROUP_INDEX = 2
+WORD_BOUNDARY_PATTERN = r"\b"
+TASK_NUMBER_REFERENCE_TEMPLATE = "#{task_id}"
+ITEM_LINE_TEMPLATE = "\n- {subject}"
+BLOCK_REASON_PREFIX = "The task list still has incomplete items that this reply does not report:"
+BLOCK_REASON_SUFFIX = (
+    "\nKeep working each one now. End the reply with one line per item you cannot finish this turn:"
+    " 'Blocked: <item> - <what the user must give>' when only the user can unblock it, or"
+    " 'Open: <item> - <the step you take next>' when you are still working it."
+)

package/hooks/session/cursor_agents_guidance.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Cursor sessionStart hook that puts the installed agent guidance into every session.
+
+Cursor keeps user rules in its app settings, and it reads ``~/.cursor/rules``
+only for a workspace inside the home directory, so no file under ``~/.cursor``
+carries global guidance. The installer registers this hook as a native
+``sessionStart`` entry in ``~/.cursor/hooks.json`` with the installed
+``AGENTS.md`` path as its one argument. The hook prints that file as Cursor's
+``additional_context``, which Cursor adds to the session's context::
+
+    python3 cursor_agents_guidance.py ~/.agents/AGENTS.md
+    -> {"additional_context": "# Agent guidance ..."}
+
+A missing or unreadable file prints ``{}`` so the session starts without it.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.cursor_agents_guidance_constants import (
+    CURSOR_CONTEXT_KEY,
+    EMPTY_OUTPUT,
+    GUIDANCE_PATH_ARGUMENT_INDEX,
+    UTF8_ENCODING,
+)
+
+
+def guidance_output(all_arguments: list[str]) -> str:
+    """Return the SessionStart output for the guidance file named in the arguments."""
+    if len(all_arguments) <= GUIDANCE_PATH_ARGUMENT_INDEX:
+        return EMPTY_OUTPUT
+    try:
+        guidance_text = Path(all_arguments[GUIDANCE_PATH_ARGUMENT_INDEX]).read_text(encoding=UTF8_ENCODING)
+    except OSError:
+        return EMPTY_OUTPUT
+    if not guidance_text.strip():
+        return EMPTY_OUTPUT
+    return json.dumps({CURSOR_CONTEXT_KEY: guidance_text})
+
+
+def main() -> None:
+    sys.stdin.read()
+    sys.stdout.write(guidance_output(sys.argv))
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/test_cursor_agents_guidance.py

@@ -0,0 +1,24 @@
+import json
+import sys
+from pathlib import Path
+
+SESSION_DIRECTORY = Path(__file__).resolve().parent
+if str(SESSION_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SESSION_DIRECTORY))
+
+import cursor_agents_guidance
+
+
+def test_should_emit_the_guidance_file_as_cursor_additional_context(tmp_path: Path) -> None:
+    guidance_path = tmp_path / "AGENTS.md"
+    guidance_path.write_text("# Agent guidance\n- **Asks.** Work every ask now.\n", encoding="utf-8")
+    printed_output = cursor_agents_guidance.guidance_output(["hook", str(guidance_path)])
+    assert json.loads(printed_output) == {"additional_context": guidance_path.read_text(encoding="utf-8")}
+
+
+def test_should_emit_an_empty_object_when_the_file_is_missing(tmp_path: Path) -> None:
+    assert cursor_agents_guidance.guidance_output(["hook", str(tmp_path / "absent.md")]) == "{}"
+
+
+def test_should_emit_an_empty_object_without_a_path_argument() -> None:
+    assert cursor_agents_guidance.guidance_output(["hook"]) == "{}"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.87.0",
+    "version": "8.88.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/scripts/policy_lint/adapter_configuration.py

@@ -139,6 +139,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/build_eval_before_eval_write_gate.py -> exempt
         hooks/blocking/merge_over_review_offer_gate.py   -> exempt
         hooks/blocking/final_reply_gate.py               -> exempt
+        hooks/blocking/open_tasks_stop_gate.py           -> exempt
         hooks/blocking/some_new_blocker.py               -> flagged
 
     The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
@@ -179,6 +180,11 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     names open review findings. It reads only the wording of a chat card and
     decides no code or safety policy; the merge review gate holds the merge.
 
+    The open tasks Stop gate holds the end of a turn while the session's task
+    list has items the closing reply neither completes nor reports as
+    ``Blocked:`` or ``Open:``. It decides when a turn may end and no code or
+    safety policy.
+
     Args:
         registered_string: One command, path, script, or entrypoint string.
     """

package/scripts/policy_lint/config/constants.py

@@ -78,6 +78,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/build_eval_before_eval_write_gate.py",
     "blocking/merge_over_review_offer_gate.py",
     "blocking/final_reply_gate.py",
+    "blocking/open_tasks_stop_gate.py",
 )
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)

package/scripts/tests/test_adapter_configuration.py

@@ -74,6 +74,14 @@ def test_new_final_reply_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_open_tasks_stop_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/open_tasks_stop_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_step_note_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/step_note_gate.py"],