claude-dev-env 8.87.1 → 8.88.0

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.1",
+    "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"],