claude-dev-env 1.57.1 → 1.58.0

package/hooks/blocking/intent_only_ending_blocker.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""
+Stop hook that blocks Claude responses ending on a promise about undone work.
+
+When a turn ends on a forward-looking statement of intent ("I'll now run the
+tests", "Let me implement the fix") instead of actually doing the work, the
+agent is forced to do the work now with tool calls, or - when genuinely blocked
+on input only the user can supply - route through AskUserQuestion and end
+cleanly. The rule name is long-horizon-autonomy.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.messages import USER_FACING_INTENT_ENDING_NOTICE  # noqa: E402
+
+
+def strip_code_and_quotes(text: str) -> str:
+    """Remove code blocks, inline code, and blockquotes to avoid false positives.
+
+    Args:
+        text: The raw assistant message to clean.
+    """
+    code_block_pattern = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+    inline_code_pattern = re.compile(r"`[^`]+`")
+    quoted_block_pattern = re.compile(r"^>.*$", re.MULTILINE)
+    text = code_block_pattern.sub("", text)
+    text = inline_code_pattern.sub("", text)
+    text = quoted_block_pattern.sub("", text)
+    return text
+
+
+def extract_final_paragraph(text: str) -> str:
+    """Return the last non-empty paragraph of the prose after stripping code and quotes.
+
+    Args:
+        text: The raw assistant message to extract the closing paragraph from.
+    """
+    paragraph_split_pattern = re.compile(r"\n\s*\n")
+    prose_text = strip_code_and_quotes(text)
+    candidate_paragraphs = [
+        each_paragraph.strip()
+        for each_paragraph in paragraph_split_pattern.split(prose_text)
+        if each_paragraph.strip()
+    ]
+    if not candidate_paragraphs:
+        return ""
+    return candidate_paragraphs[-1]
+
+
+def extract_first_sentence(paragraph: str) -> str:
+    """Return the first sentence of a paragraph.
+
+    Args:
+        paragraph: The paragraph whose leading sentence is needed.
+    """
+    sentence_boundary_pattern = re.compile(r"(?<=[.!?])\s+")
+    sentences = sentence_boundary_pattern.split(paragraph.strip(), maxsplit=1)
+    if not sentences:
+        return ""
+    return sentences[0].strip()
+
+
+def find_intent_only_ending(text: str) -> bool:
+    """Return whether the final paragraph ends the turn on a promise about undone work.
+
+    Args:
+        text: The raw assistant message to evaluate.
+    """
+    future_intent_opener_pattern = re.compile(
+        r"^(?:(?:now|next|then|okay|alright)\s*,?\s*)?"
+        r"(?:i['’]ll(?:\s+now|\s+go\s+ahead\s+and|\s+proceed\s+to)?"
+        r"|i\s+will"
+        r"|i['’]m\s+going\s+to"
+        r"|i\s+am\s+going\s+to"
+        r"|i['’]m\s+about\s+to"
+        r"|i\s+plan\s+to"
+        r"|let\s+me"
+        r"|let['’]s"
+        r"|going\s+to)\b",
+        re.IGNORECASE,
+    )
+    undone_work_verb_pattern = re.compile(
+        r"\b(?:run|start|implement|create|write|add|fix|update|check|test|wire"
+        r"|build|deploy|push|git\s+commit|commit\s+the\s+changes"
+        r"|commit\s+the\s+fix|investigate|set\s+up|refactor|generate"
+        r"|install|continue|look\s+into)\b",
+        re.IGNORECASE,
+    )
+    next_steps_lead_in_pattern = re.compile(r"^next\s+steps?:", re.IGNORECASE)
+    second_person_subject_pattern = re.compile(
+        r"\b(?:you|your|you['’]?re|user['’]?s?)\b",
+        re.IGNORECASE,
+    )
+
+    final_paragraph = extract_final_paragraph(text)
+    if not final_paragraph:
+        return False
+
+    if next_steps_lead_in_pattern.match(final_paragraph):
+        return not second_person_subject_pattern.search(final_paragraph)
+
+    first_sentence = extract_first_sentence(final_paragraph)
+    if not future_intent_opener_pattern.match(first_sentence):
+        return False
+
+    return bool(undone_work_verb_pattern.search(first_sentence))
+
+
+def main() -> None:
+    """Read the stop-hook payload and block turns that end on a promise of undone work."""
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if hook_input.get("stop_hook_active", False):
+        sys.exit(0)
+
+    assistant_message = hook_input.get("last_assistant_message", "")
+
+    if not assistant_message:
+        sys.exit(0)
+
+    if not find_intent_only_ending(assistant_message):
+        sys.exit(0)
+
+    block_response = {
+        "decision": "block",
+        "reason": (
+            "LONG-HORIZON-AUTONOMY GUARDRAIL: Your turn ends on a promise about work "
+            "that is not yet done, rather than doing it. Do the work NOW with tool calls "
+            "instead of describing what you are about to do.\n\n"
+            "If the work is genuinely blocked on input only the user can give, route the "
+            "ask through an AskUserQuestion tool call and end the turn cleanly. Otherwise, "
+            "carry out the stated action this turn.\n\n"
+            "You MUST re-output the complete response with the work actually performed, "
+            "per the long-horizon-autonomy rule."
+        ),
+        "systemMessage": USER_FACING_INTENT_ENDING_NOTICE,
+        "suppressOutput": True,
+    }
+
+    print(json.dumps(block_response))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/session_handoff_blocker.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""
+Stop hook that blocks Claude responses proposing to stop on account of context.
+
+When a turn proposes stopping, summarizing to hand off, or starting a new
+session because of context or token limits, the agent is reassured that ample
+context remains and forced to continue the work. A mere topical mention of the
+word "context" does not fire - only a self-termination or handoff proposal does.
+The rule name is long-horizon-autonomy.
+"""
+
+import json
+import re
+import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.messages import USER_FACING_CONTEXT_REASSURANCE_NOTICE  # noqa: E402
+from hooks_constants.session_handoff_blocker_constants import (  # noqa: E402
+    FIRST_PERSON_SUBJECT_PATTERN,
+)
+
+
+def strip_code_and_quotes(text: str) -> str:
+    """Remove code blocks, inline code, and blockquotes to avoid false positives.
+
+    Args:
+        text: The raw assistant message to clean.
+    """
+    code_block_pattern = re.compile(r"```[\s\S]*?```", re.MULTILINE)
+    inline_code_pattern = re.compile(r"`[^`]+`")
+    quoted_block_pattern = re.compile(r"^>.*$", re.MULTILINE)
+    text = code_block_pattern.sub("", text)
+    text = inline_code_pattern.sub("", text)
+    text = quoted_block_pattern.sub("", text)
+    return text
+
+
+def split_into_sentences(text: str) -> list[str]:
+    """Return the non-empty sentences of the prose.
+
+    Args:
+        text: The prose to split on sentence boundaries.
+    """
+    sentence_boundary_pattern = re.compile(r"(?<=[.!?])\s+")
+    return [
+        each_sentence.strip()
+        for each_sentence in sentence_boundary_pattern.split(text)
+        if each_sentence.strip()
+    ]
+
+
+def has_first_person_self_termination(text: str) -> bool:
+    """Return whether any sentence binds a first-person subject to a stop or handoff cue.
+
+    Args:
+        text: The prose to scan sentence by sentence.
+    """
+    self_termination_cue_pattern = re.compile(
+        r"\b(?:stop|summari[sz]\w*|wrap\s+up|wrap\s+things\s+up"
+        r"|hand\s+(?:off|it\s+off|this\s+off)|pause"
+        r"|continue\s+(?:this|later)|pick\s+(?:this|it)\s+up"
+        r"|new\s+session|fresh\s+session|separate\s+session|clean\s+session"
+        r"|running\s+(?:low|out)\s+(?:on|of)\s+(?:context|tokens)"
+        r"|(?:low|short)\s+on\s+(?:context|tokens))\b",
+        re.IGNORECASE,
+    )
+    for each_sentence in split_into_sentences(text):
+        if FIRST_PERSON_SUBJECT_PATTERN.search(
+            each_sentence
+        ) and self_termination_cue_pattern.search(each_sentence):
+            return True
+    return False
+
+
+def has_resource_reference_with_handoff_cue(text: str) -> bool:
+    """Return whether any sentence pairs a context/token reference with a stop cue.
+
+    Args:
+        text: The prose to scan sentence by sentence.
+    """
+    resource_reference_pattern = re.compile(
+        r"\b(?:context|token)\s+(?:budget|window|limit|count|usage)\b"
+        r"|\b(?:low|short)\s+on\s+(?:context|tokens)\b"
+        r"|\bto\s+(?:save|conserve|preserve|free\s+up)\s+(?:context|tokens)\b",
+        re.IGNORECASE,
+    )
+    stop_or_handoff_cue_pattern = re.compile(
+        r"\b(?:stop|summari[sz]\w*|wrap\s+up|wrap\s+things\s+up|hand\s+off"
+        r"|new\s+session|pause|continue\s+later|pick\s+this\s+up\s+later)\b",
+        re.IGNORECASE,
+    )
+    for each_sentence in split_into_sentences(text):
+        if resource_reference_pattern.search(
+            each_sentence
+        ) and stop_or_handoff_cue_pattern.search(each_sentence):
+            return True
+    return False
+
+
+def has_first_person_direct_handoff(text: str) -> bool:
+    """Return whether any sentence binds a first-person subject to a direct-handoff cue.
+
+    Args:
+        text: The prose to scan sentence by sentence.
+    """
+    new_session_proposal_pattern = re.compile(
+        r"\b(?:wrap\s+up|wrap\s+things\s+up|hand\s+off|hand\s+this\s+off"
+        r"|hand\s+it\s+off|continue\s+this|continue\s+later|pick\s+this\s+up"
+        r"|pick\s+it\s+up|pause|resume)\b"
+        r"[^.!?]*"
+        r"\b(?:a\s+|the\s+)?(?:new|fresh|separate|clean)\s+session\b",
+        re.IGNORECASE,
+    )
+    running_low_pattern = re.compile(
+        r"\brunning\s+(?:low|out)\s+(?:on|of)\s+(?:context|tokens)\b",
+        re.IGNORECASE,
+    )
+    all_direct_handoff_patterns = [
+        new_session_proposal_pattern,
+        running_low_pattern,
+    ]
+    for each_sentence in split_into_sentences(text):
+        if not FIRST_PERSON_SUBJECT_PATTERN.search(each_sentence):
+            continue
+        if any(
+            each_pattern.search(each_sentence)
+            for each_pattern in all_direct_handoff_patterns
+        ):
+            return True
+    return False
+
+
+def find_session_handoff_proposal(text: str) -> bool:
+    """Return whether the message proposes stopping on account of context or tokens.
+
+    Args:
+        text: The raw assistant message to evaluate.
+    """
+    prose_text = strip_code_and_quotes(text)
+
+    if not has_first_person_self_termination(prose_text):
+        return False
+
+    if has_first_person_direct_handoff(prose_text):
+        return True
+
+    return has_resource_reference_with_handoff_cue(prose_text)
+
+
+def main() -> None:
+    """Read the stop-hook payload and block turns proposing a context-driven handoff."""
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if hook_input.get("stop_hook_active", False):
+        sys.exit(0)
+
+    assistant_message = hook_input.get("last_assistant_message", "")
+
+    if not assistant_message:
+        sys.exit(0)
+
+    if not find_session_handoff_proposal(assistant_message):
+        sys.exit(0)
+
+    block_response = {
+        "decision": "block",
+        "reason": (
+            "LONG-HORIZON-AUTONOMY GUARDRAIL: You have ample context remaining. Do not "
+            "stop, summarize, or suggest a new session on account of context limits. "
+            "Continue the work.\n\n"
+            "Re-output your response continuing the task without the handoff suggestion, "
+            "per the long-horizon-autonomy rule."
+        ),
+        "systemMessage": USER_FACING_CONTEXT_REASSURANCE_NOTICE,
+        "suppressOutput": True,
+    }
+
+    print(json.dumps(block_response))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/test_intent_only_ending_blocker.py

@@ -0,0 +1,175 @@
+"""Tests for intent_only_ending_blocker hook response shape."""
+
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+
+HOOK_SCRIPT_PATH = os.path.join(os.path.dirname(__file__), "intent_only_ending_blocker.py")
+_HOOKS_DIR = os.path.dirname(HOOK_SCRIPT_PATH)
+_HOOKS_ROOT = os.path.join(_HOOKS_DIR, "..")
+_HOOK_CONFIG_DIR = os.path.join(_HOOKS_ROOT, "hooks_constants")
+if _HOOKS_DIR not in sys.path:
+    sys.path.insert(0, _HOOKS_DIR)
+if _HOOKS_ROOT not in sys.path:
+    sys.path.insert(0, _HOOKS_ROOT)
+import intent_only_ending_blocker
+from hooks_constants.messages import USER_FACING_INTENT_ENDING_NOTICE
+
+INTENT_ENDING_MESSAGE = "I'll now run the test suite and fix any failures that come up."
+NEXT_STEPS_MESSAGE = "Next steps:"
+COMPLETED_WORK_MESSAGE = "Done - all tests pass. The fix is in place."
+BENIGN_PAST_TENSE_MESSAGE = "I implemented the parser and verified it against the fixtures."
+CLEAN_MESSAGE = "The function returns the parsed payload to its caller."
+COMMITMENT_PHRASING_MESSAGE = "I'll commit to keeping the API stable across the next release."
+NAMING_COMMITMENT_MESSAGE = "Let me commit to a clear naming convention for these helpers."
+GIT_COMMIT_INTENT_MESSAGE = "I'll commit the changes once the tests pass."
+DEFERRED_TO_USER_CI_RUNS_MESSAGE = (
+    "Let me know if this looks right. The CI will run automatically on push."
+)
+DEFERRED_TO_USER_EITHER_WAY_MESSAGE = (
+    "Let me know which option you want. I can check either way."
+)
+USER_DIRECTED_NEXT_STEPS_MESSAGE = (
+    "All done. The PR is merged.\n\nNext steps: you should deploy when ready."
+)
+EMPTY_MESSAGE = ""
+
+
+def run_hook_with_message(assistant_message: str) -> subprocess.CompletedProcess:
+    hook_input_payload = json.dumps({"last_assistant_message": assistant_message})
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=hook_input_payload,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def run_hook_with_payload(hook_input_payload: dict) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, HOOK_SCRIPT_PATH],
+        input=json.dumps(hook_input_payload),
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def test_user_facing_notice_matches_config_messages_module():
+    config_messages_path = os.path.join(_HOOK_CONFIG_DIR, "messages.py")
+    specification = importlib.util.spec_from_file_location("messages", config_messages_path)
+    module = importlib.util.module_from_spec(specification)
+    specification.loader.exec_module(module)
+
+    assert module.USER_FACING_INTENT_ENDING_NOTICE == USER_FACING_INTENT_ENDING_NOTICE
+    assert (
+        intent_only_ending_blocker.USER_FACING_INTENT_ENDING_NOTICE
+        == module.USER_FACING_INTENT_ENDING_NOTICE
+    )
+
+
+def test_intent_ending_message_emits_block_with_short_user_notice():
+    completed_process = run_hook_with_message(INTENT_ENDING_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_INTENT_ENDING_NOTICE
+    assert parsed_response["suppressOutput"] is True
+    assert "long-horizon-autonomy" in parsed_response["reason"]
+
+
+def test_next_steps_lead_in_emits_block():
+    completed_process = run_hook_with_message(NEXT_STEPS_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_INTENT_ENDING_NOTICE
+
+
+def test_completed_work_summary_passes_through_with_no_output():
+    completed_process = run_hook_with_message(COMPLETED_WORK_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_past_tense_summary_passes_through_with_no_output():
+    completed_process = run_hook_with_message(BENIGN_PAST_TENSE_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_commitment_phrasing_passes_through_with_no_output():
+    completed_process = run_hook_with_message(COMMITMENT_PHRASING_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_naming_commitment_passes_through_with_no_output():
+    completed_process = run_hook_with_message(NAMING_COMMITMENT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_git_commit_intent_emits_block():
+    completed_process = run_hook_with_message(GIT_COMMIT_INTENT_MESSAGE)
+
+    assert completed_process.returncode == 0
+    parsed_response = json.loads(completed_process.stdout)
+
+    assert parsed_response["decision"] == "block"
+    assert parsed_response["systemMessage"] == USER_FACING_INTENT_ENDING_NOTICE
+
+
+def test_benign_opener_with_unrelated_work_verb_passes_through_with_no_output():
+    completed_process = run_hook_with_message(DEFERRED_TO_USER_CI_RUNS_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_deferral_to_user_with_later_verb_passes_through_with_no_output():
+    completed_process = run_hook_with_message(DEFERRED_TO_USER_EITHER_WAY_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_user_directed_next_steps_passes_through_with_no_output():
+    completed_process = run_hook_with_message(USER_DIRECTED_NEXT_STEPS_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_clean_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(CLEAN_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_empty_message_passes_through_with_no_output():
+    completed_process = run_hook_with_message(EMPTY_MESSAGE)
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""
+
+
+def test_stop_hook_active_short_circuits_with_no_output():
+    completed_process = run_hook_with_payload(
+        {"last_assistant_message": INTENT_ENDING_MESSAGE, "stop_hook_active": True}
+    )
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout == ""