claude-dev-env 8.87.0 → 8.88.0

package/hooks/blocking/open_tasks_stop_gate.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Stop hook that keeps a session working while its task list has unreported open items.
+
+The session's task list comes from the first of these that exists::
+
+    ~/.claude/tasks/<task list id>/*.json     (TaskCreate / TaskUpdate store)
+    transcript TaskCreate / TaskUpdate calls   (replayed in order)
+    transcript TodoWrite input.todos           (last call wins)
+    transcript Codex update_plan arguments     (last call wins)
+
+An item with status ``pending`` or ``in_progress`` is open. The turn may end
+only when the closing reply names every open item on a report line::
+
+    allow: Blocked: Rotate the deploy key - the owner must approve the org secret
+    allow: - Open: #3 - waits on the release checks
+    block: (reply never mentions "Rotate the deploy key")
+
+A block sends the open items back as the reason, so the model keeps working or
+reports them. Claude Code ends the turn after eight blocks in a row. Codex
+turns the reason into a continuation prompt. A Cursor payload (it carries
+``conversation_id``) also gets the reason as ``followup_message``, which
+Cursor submits as the next user message; Cursor sends no closing reply, so
+the gate reads the last assistant text from the transcript. A Cursor payload
+whose ``status`` is ``aborted`` or ``error`` is allowed, because Cursor would
+submit the follow-up after the user stopped the run, and so is one whose
+``loop_count`` shows five follow-ups already sent. A TodoWrite call with
+``merge`` set updates the earlier items by id, and a Cursor ``CallDynamicTool``
+call that wraps TodoWrite counts as that TodoWrite call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+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)
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from open_tasks_transcript import TaskItem, parsed_object, replayed_transcript
+from hooks_constants.open_tasks_stop_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    BLOCK_REASON_PREFIX,
+    BLOCK_REASON_SUFFIX,
+    CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE,
+    CLAUDE_HOME_DIRECTORY_NAME,
+    CURSOR_COMPLETED_STATUS,
+    CURSOR_CONVERSATION_ID_KEY,
+    CURSOR_FOLLOWUP_LIMIT,
+    CURSOR_FOLLOWUP_MESSAGE_KEY,
+    CURSOR_LOOP_COUNT_KEY,
+    CURSOR_STATUS_KEY,
+    DECISION_KEY,
+    HOOK_EVENT_NAME,
+    INCOMPLETE_STATUSES,
+    ITEM_LINE_TEMPLATE,
+    LAST_ASSISTANT_MESSAGE_KEY,
+    REASON_KEY,
+    REPORT_LINE_PATTERN,
+    REPORTED_TEXT_GROUP_INDEX,
+    SESSION_ID_KEY,
+    TASK_FILE_GLOB,
+    TASK_ID_KEY,
+    TASK_LIST_ID_ENVIRONMENT_VARIABLE,
+    TASK_NUMBER_REFERENCE_TEMPLATE,
+    TASK_STATUS_KEY,
+    TASK_SUBJECT_KEY,
+    TASKS_DIRECTORY_NAME,
+    TRANSCRIPT_PATH_KEY,
+    UTF8_ENCODING,
+    WORD_BOUNDARY_PATTERN,
+    WORD_SEPARATOR,
+)
+
+
+def _claude_home() -> Path:
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE)
+    if configured_directory:
+        return Path(configured_directory)
+    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME
+
+
+def _task_file_item(task_file: Path) -> TaskItem | None:
+    try:
+        task_text = task_file.read_text(encoding=UTF8_ENCODING)
+    except OSError:
+        return None
+    all_task_fields = parsed_object(task_text)
+    if all_task_fields is None:
+        return None
+    return TaskItem(
+        str(all_task_fields.get(TASK_ID_KEY, task_file.stem)),
+        str(all_task_fields.get(TASK_SUBJECT_KEY, "")),
+        str(all_task_fields.get(TASK_STATUS_KEY, "")),
+    )
+
+
+def task_store_items(session_id: object) -> list[TaskItem] | None:
+    """Return the task store items for the session, or None when no store exists."""
+    task_list_id = os.environ.get(TASK_LIST_ID_ENVIRONMENT_VARIABLE) or session_id
+    if not isinstance(task_list_id, str) or not task_list_id:
+        return None
+    task_directory = _claude_home() / TASKS_DIRECTORY_NAME / task_list_id
+    if not task_directory.is_dir():
+        return None
+    all_items = (_task_file_item(each_file) for each_file in sorted(task_directory.glob(TASK_FILE_GLOB)))
+    return [each_item for each_item in all_items if each_item is not None]
+
+
+def _normalized(text: str) -> str:
+    return WORD_SEPARATOR.join(text.lower().split())
+
+
+def _reported_texts(reply_text: str) -> list[str]:
+    all_matches = (re.match(REPORT_LINE_PATTERN, each_line, re.IGNORECASE) for each_line in reply_text.splitlines())
+    return [_normalized(each_match.group(REPORTED_TEXT_GROUP_INDEX)) for each_match in all_matches if each_match]
+
+
+def is_reported(task_item: TaskItem, reply_text: str) -> bool:
+    """Return True when a Blocked: or Open: line of the reply names the item."""
+    subject_text = _normalized(task_item.subject)
+    number_pattern = re.escape(TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=task_item.item_id)) + WORD_BOUNDARY_PATTERN
+    return any(
+        (subject_text and subject_text in each_text) or re.search(number_pattern, each_text)
+        for each_text in _reported_texts(reply_text)
+    )
+
+
+def unreported_open_items(all_hook_input_fields: dict[str, object]) -> list[TaskItem]:
+    """Return the open task items the closing reply does not report."""
+    replay = replayed_transcript(all_hook_input_fields.get(TRANSCRIPT_PATH_KEY))
+    all_items = task_store_items(all_hook_input_fields.get(SESSION_ID_KEY))
+    if all_items is None:
+        all_items = replay.items() or []
+    reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
+    reply_text = reply_value if isinstance(reply_value, str) else replay.last_assistant_text
+    return [
+        each_item
+        for each_item in all_items
+        if each_item.status in INCOMPLETE_STATUSES and not is_reported(each_item, reply_text)
+    ]
+
+
+def block_reason_for(all_open_items: list[TaskItem]) -> str:
+    """Return the block reason that lists each open item."""
+    all_item_lines = (
+        ITEM_LINE_TEMPLATE.format(subject=each_item.subject or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=each_item.item_id))
+        for each_item in all_open_items
+    )
+    return BLOCK_REASON_PREFIX + "".join(all_item_lines) + BLOCK_REASON_SUFFIX
+
+
+def block_output_for(all_hook_input_fields: dict[str, object], block_reason: str) -> dict[str, str]:
+    """Return the block output; a Cursor payload also gets the reason as ``followup_message``."""
+    block_output = {DECISION_KEY: BLOCK_DECISION, REASON_KEY: block_reason}
+    if all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        block_output[CURSOR_FOLLOWUP_MESSAGE_KEY] = block_reason
+    return block_output
+
+
+def is_unfinished_cursor_stop(all_hook_input_fields: dict[str, object]) -> bool:
+    """Return True for a Cursor stop whose run was aborted or ended in an error."""
+    if not all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        return False
+    stop_status = all_hook_input_fields.get(CURSOR_STATUS_KEY)
+    return stop_status is not None and stop_status != CURSOR_COMPLETED_STATUS
+
+
+def has_spent_cursor_followups(all_hook_input_fields: dict[str, object]) -> bool:
+    """Return True for a Cursor stop that already sent the follow-up limit.
+
+    Cursor caps native stop follow-ups at five per script, but a copy it imports
+    from ``~/.claude/settings.json`` has no cap, so the gate stops at five itself.
+    """
+    if not all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        return False
+    loop_count = all_hook_input_fields.get(CURSOR_LOOP_COUNT_KEY)
+    return isinstance(loop_count, int) and loop_count >= CURSOR_FOLLOWUP_LIMIT
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None or is_unfinished_cursor_stop(hook_input) or has_spent_cursor_followups(hook_input):
+        return ALLOW_EXIT_CODE
+    all_open_items = unreported_open_items(hook_input)
+    if not all_open_items:
+        return ALLOW_EXIT_CODE
+    block_reason = block_reason_for(all_open_items)
+    reply_value = hook_input.get(LAST_ASSISTANT_MESSAGE_KEY)
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        offending_input_preview=reply_value if isinstance(reply_value, str) else None,
+    )
+    sys.stdout.write(json.dumps(block_output_for(hook_input, block_reason)))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/open_tasks_transcript.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""Rebuild a session task list and its last assistant text from a transcript.
+
+The open tasks Stop gate reads three transcript shapes, replayed in order::
+
+    TaskCreate / TaskUpdate calls        (Claude Code)
+    TodoWrite input.todos                (Claude Code and Cursor; ``merge`` updates by id)
+    update_plan function_call arguments  (Codex rollout)
+
+The Cursor CLI can also reach TodoWrite through ``CallDynamicTool``, with the
+TodoWrite input under ``arguments``; that call counts as the TodoWrite call.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+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.open_tasks_stop_gate_constants import (
+    ASSISTANT_ROLE,
+    CODEX_ARGUMENTS_KEY,
+    CODEX_FUNCTION_CALL_TYPE,
+    CODEX_PAYLOAD_KEY,
+    CODEX_PLAN_KEY,
+    CODEX_PLAN_TOOL_NAME,
+    CODEX_RESPONSE_ITEM_TYPE,
+    CODEX_STEP_KEY,
+    CONTENT_KEY,
+    CREATED_TASK_ID_GROUP_INDEX,
+    DYNAMIC_TOOL_ARGUMENTS_KEY,
+    DYNAMIC_TOOL_CALL_NAME,
+    DYNAMIC_TOOL_NAME_KEY,
+    FIRST_ITEM_NUMBER,
+    MESSAGE_KEY,
+    PENDING_STATUS,
+    RECORD_TYPE_KEY,
+    REPLY_TEXT_SEPARATOR,
+    ROLE_KEY,
+    TASK_CREATED_PATTERN,
+    TASK_CREATE_TOOL_NAME,
+    TASK_ID_KEY,
+    TASK_STATUS_KEY,
+    TASK_SUBJECT_KEY,
+    TASK_UPDATE_ID_KEY,
+    TASK_UPDATE_TOOL_NAME,
+    TEXT_KEY,
+    TODOS_KEY,
+    TODO_CONTENT_KEY,
+    TODO_ID_KEY,
+    TODO_MERGE_KEY,
+    TODO_WRITE_TOOL_NAME,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    TOOL_RESULT_BLOCK_TYPE,
+    TOOL_USE_BLOCK_TYPE,
+    TOOL_USE_ID_KEY,
+    UTF8_ENCODING,
+    WORD_SEPARATOR,
+)
+
+
+class TaskItem(NamedTuple):
+    """One task list item.
+
+    Attributes:
+        item_id: The task number or position, as text.
+        subject: The item's wording.
+        status: The item's status, such as ``pending`` or ``completed``.
+    """
+
+    item_id: str
+    subject: str
+    status: str
+
+
+def parsed_object(json_text: str) -> dict[str, object] | None:
+    """Return the JSON object in the text, or None for anything else."""
+    try:
+        parsed_value = json.loads(json_text)
+    except ValueError:
+        return None
+    return parsed_value if isinstance(parsed_value, dict) else None
+
+
+def _transcript_records(transcript_path: object) -> list[dict[str, object]]:
+    if not isinstance(transcript_path, str):
+        return []
+    try:
+        all_lines = Path(transcript_path).read_text(encoding=UTF8_ENCODING).splitlines()
+    except OSError:
+        return []
+    all_records = (parsed_object(each_line) for each_line in all_lines)
+    return [each_record for each_record in all_records if each_record is not None]
+
+
+def _content_blocks(all_record_fields: dict[str, object]) -> list[dict[str, object]]:
+    message_body = all_record_fields.get(MESSAGE_KEY)
+    content_value = message_body.get(CONTENT_KEY) if isinstance(message_body, dict) else None
+    if not isinstance(content_value, list):
+        return []
+    return [each_block for each_block in content_value if isinstance(each_block, dict)]
+
+
+def _result_text(all_block_fields: dict[str, object]) -> str:
+    result_content = all_block_fields.get(CONTENT_KEY)
+    if isinstance(result_content, str):
+        return result_content
+    if not isinstance(result_content, list):
+        return ""
+    return WORD_SEPARATOR.join(
+        str(each_part.get(TEXT_KEY, "")) for each_part in result_content if isinstance(each_part, dict)
+    )
+
+
+def _numbered_items(all_entries: object, subject_key: str) -> list[TaskItem]:
+    if not isinstance(all_entries, list):
+        return []
+    all_dictionaries = [each_entry for each_entry in all_entries if isinstance(each_entry, dict)]
+    return [
+        TaskItem(str(each_number), str(each_entry.get(subject_key, "")), str(each_entry.get(TASK_STATUS_KEY, "")))
+        for each_number, each_entry in enumerate(all_dictionaries, start=FIRST_ITEM_NUMBER)
+    ]
+
+
+def _todo_items(all_todo_entries: object) -> list[TaskItem]:
+    if not isinstance(all_todo_entries, list):
+        return []
+    all_dictionaries = [each_entry for each_entry in all_todo_entries if isinstance(each_entry, dict)]
+    return [
+        TaskItem(
+            str(each_entry.get(TODO_ID_KEY, each_number)),
+            str(each_entry.get(TODO_CONTENT_KEY, "")),
+            str(each_entry.get(TASK_STATUS_KEY, "")),
+        )
+        for each_number, each_entry in enumerate(all_dictionaries, start=FIRST_ITEM_NUMBER)
+    ]
+
+
+def merged_todo_items(all_earlier_items: list[TaskItem], all_update_entries: object) -> list[TaskItem]:
+    """Apply a ``merge`` TodoWrite call: update earlier items by id and append new ones."""
+    item_by_id = {each_item.item_id: each_item for each_item in all_earlier_items}
+    for each_update in _todo_items(all_update_entries):
+        earlier_item = item_by_id.get(each_update.item_id)
+        if earlier_item is None:
+            item_by_id[each_update.item_id] = each_update
+            continue
+        item_by_id[each_update.item_id] = earlier_item._replace(
+            subject=each_update.subject or earlier_item.subject,
+            status=each_update.status or earlier_item.status,
+        )
+    return list(item_by_id.values())
+
+
+def codex_plan_items(all_record_fields: dict[str, object]) -> list[TaskItem] | None:
+    """Return the plan from a Codex rollout ``update_plan`` call record, or None for any other record."""
+    payload_body = all_record_fields.get(CODEX_PAYLOAD_KEY)
+    if all_record_fields.get(RECORD_TYPE_KEY) != CODEX_RESPONSE_ITEM_TYPE or not isinstance(payload_body, dict):
+        return None
+    if payload_body.get(RECORD_TYPE_KEY) != CODEX_FUNCTION_CALL_TYPE or payload_body.get(TOOL_NAME_KEY) != CODEX_PLAN_TOOL_NAME:
+        return None
+    all_plan_arguments = parsed_object(str(payload_body.get(CODEX_ARGUMENTS_KEY, "")))
+    if all_plan_arguments is None:
+        return None
+    return _numbered_items(all_plan_arguments.get(CODEX_PLAN_KEY), CODEX_STEP_KEY)
+
+
+def unwrapped_tool_call(tool_name: str, all_input_fields: dict[str, object]) -> tuple[str, dict[str, object]]:
+    """Return the inner tool name and arguments of a Cursor ``CallDynamicTool`` call, or the call itself.
+
+    The Cursor CLI can reach TodoWrite through ``CallDynamicTool`` with
+    ``{"toolName": "TodoWrite", "arguments": {"todos": [...], "merge": true}}``.
+    """
+    inner_name = all_input_fields.get(DYNAMIC_TOOL_NAME_KEY)
+    all_inner_arguments = all_input_fields.get(DYNAMIC_TOOL_ARGUMENTS_KEY)
+    if tool_name != DYNAMIC_TOOL_CALL_NAME or not isinstance(inner_name, str) or not isinstance(all_inner_arguments, dict):
+        return tool_name, all_input_fields
+    return inner_name, all_inner_arguments
+
+
+class _TranscriptReplay:
+    """Fold transcript records into the newest task list they describe."""
+
+    def __init__(self) -> None:
+        self.latest_items: list[TaskItem] | None = None
+        self.created_by_id: dict[str, TaskItem] = {}
+        self.subject_by_tool_use_id: dict[str, str] = {}
+        self.last_assistant_text = ""
+
+    def apply_record(self, all_record_fields: dict[str, object]) -> None:
+        plan_items = codex_plan_items(all_record_fields)
+        if plan_items is not None:
+            self.latest_items = plan_items
+            return
+        all_blocks = _content_blocks(all_record_fields)
+        for each_block in all_blocks:
+            self.apply_block(each_block)
+        self.note_assistant_text(all_record_fields, all_blocks)
+
+    def note_assistant_text(self, all_record_fields: dict[str, object], all_blocks: list[dict[str, object]]) -> None:
+        message_body = all_record_fields.get(MESSAGE_KEY)
+        message_role = message_body.get(ROLE_KEY) if isinstance(message_body, dict) else None
+        if ASSISTANT_ROLE not in (all_record_fields.get(ROLE_KEY), all_record_fields.get(RECORD_TYPE_KEY), message_role):
+            return
+        record_text = REPLY_TEXT_SEPARATOR.join(
+            str(each_block.get(TEXT_KEY, "")) for each_block in all_blocks if each_block.get(RECORD_TYPE_KEY) == TEXT_KEY
+        ).strip()
+        if record_text:
+            self.last_assistant_text = record_text
+
+    def apply_block(self, all_block_fields: dict[str, object]) -> None:
+        block_type = all_block_fields.get(RECORD_TYPE_KEY)
+        tool_input = all_block_fields.get(TOOL_INPUT_KEY)
+        if block_type == TOOL_USE_BLOCK_TYPE and isinstance(tool_input, dict):
+            tool_name, all_tool_arguments = unwrapped_tool_call(str(all_block_fields.get(TOOL_NAME_KEY)), tool_input)
+            self.apply_tool_use(tool_name, str(all_block_fields.get(TASK_ID_KEY)), all_tool_arguments)
+        elif block_type == TOOL_RESULT_BLOCK_TYPE:
+            self.apply_tool_result(all_block_fields)
+
+    def apply_tool_use(self, tool_name: str, tool_use_id: str, all_input_fields: dict[str, object]) -> None:
+        if tool_name == TODO_WRITE_TOOL_NAME:
+            all_todo_entries = all_input_fields.get(TODOS_KEY)
+            is_merge = all_input_fields.get(TODO_MERGE_KEY) is True and self.latest_items is not None
+            self.latest_items = (
+                merged_todo_items(self.latest_items or [], all_todo_entries) if is_merge else _todo_items(all_todo_entries)
+            )
+            return
+        if tool_name == TASK_CREATE_TOOL_NAME:
+            self.subject_by_tool_use_id[tool_use_id] = str(all_input_fields.get(TASK_SUBJECT_KEY, ""))
+            return
+        if tool_name == TASK_UPDATE_TOOL_NAME:
+            self.apply_task_update(all_input_fields)
+
+    def apply_task_update(self, all_input_fields: dict[str, object]) -> None:
+        task_id = str(all_input_fields.get(TASK_UPDATE_ID_KEY, ""))
+        new_status = all_input_fields.get(TASK_STATUS_KEY)
+        if task_id in self.created_by_id and new_status:
+            self.created_by_id[task_id] = self.created_by_id[task_id]._replace(status=str(new_status))
+
+    def apply_tool_result(self, all_block_fields: dict[str, object]) -> None:
+        created_subject = self.subject_by_tool_use_id.pop(str(all_block_fields.get(TOOL_USE_ID_KEY)), None)
+        created_match = re.search(TASK_CREATED_PATTERN, _result_text(all_block_fields))
+        if created_subject is None or created_match is None:
+            return
+        created_id = created_match.group(CREATED_TASK_ID_GROUP_INDEX)
+        self.created_by_id[created_id] = TaskItem(created_id, created_subject, PENDING_STATUS)
+
+    def items(self) -> list[TaskItem] | None:
+        if self.created_by_id:
+            return list(self.created_by_id.values())
+        return self.latest_items
+
+
+def replayed_transcript(transcript_path: object) -> _TranscriptReplay:
+    """Fold every transcript record into one replay of the task list and the last assistant text."""
+    replay = _TranscriptReplay()
+    for each_record in _transcript_records(transcript_path):
+        replay.apply_record(each_record)
+    return replay
+
+
+def transcript_items(transcript_path: object) -> list[TaskItem] | None:
+    """Rebuild the task list from TaskCreate/TaskUpdate, TodoWrite, and Codex update_plan calls."""
+    return replayed_transcript(transcript_path).items()