claude-dev-env 1.57.2 → 1.59.0

package/hooks/blocking/hook_prose_detector_consistency.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block a hook module whose prose overstates its path-shape detector.
+
+A path-shape blocker hook detects a per-iteration token only when the token sits
+next to a path separator (its detection regex keys off a `[\\/]`-style character
+class). When such a hook's user-facing prose -- its module docstring lead
+narrative or its CORRECTIVE_MESSAGE -- also claims it blocks an "output-key
+segment", the prose describes a trigger the detector never fires on: a quoted
+structured-output key alone, with no looped path, is never blocked.
+
+This drift misleads two audiences at once. An author whose only per-iteration
+token is an output key never sees the block, yet the message implies they would.
+An author who does see the block is told an output key caused it, when only the
+path-adjacent shape did.
+
+Detection strategy: act only on Write/Edit to a `.py` file under `hooks/`. The
+prose claim -- the phrase "output-key segment" describing a blocked trigger --
+is the violation. A `*_constants.py` companion holds only the corrective message
+and never the detector, so that file is flagged on the claim alone. Any other
+hook module is flagged when it also keys a detection regex off a path-separator
+character class (a `[...\\...]`/`[.../...]` class), proving the co-located
+detector is path-shape only and the docstring claim overstates it.
+
+This detector's own three source files -- the hook module, its `*_constants.py`
+companion, and its `test_*` module -- carry the forbidden phrase and the
+separator-class shape as load-bearing description, so they are exempt by basename
+and stay editable through the harness this rule runs in.
+
+Fails OPEN (approves) on malformed input or a non-hook path; the invariant is
+narrow enough that a false negative is preferable to blocking unrelated edits.
+"""
+
+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.hook_prose_detector_consistency_constants import (  # noqa: E402
+    CONSTANTS_MODULE_SUFFIX,
+    CORRECTIVE_MESSAGE,
+    EDIT_TOOL_NAME,
+    HOOK_MODULE_PATH_SEGMENT,
+    OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN,
+    PATH_SEPARATOR_CLASS_PATTERN,
+    PYTHON_FILE_SUFFIX,
+    TEST_MODULE_PREFIX,
+    WRITE_TOOL_NAME,
+)
+
+
+def written_content(tool_name: str, all_tool_input: dict[str, object]) -> str:
+    if tool_name == WRITE_TOOL_NAME:
+        content = all_tool_input.get("content", "")
+        return content if isinstance(content, str) else ""
+    if tool_name == EDIT_TOOL_NAME:
+        new_string = all_tool_input.get("new_string", "")
+        return new_string if isinstance(new_string, str) else ""
+    return ""
+
+
+def target_path(all_tool_input: dict[str, object]) -> str:
+    file_path = all_tool_input.get("file_path", "")
+    return file_path if isinstance(file_path, str) else ""
+
+
+def is_hook_python_module(file_path: str) -> bool:
+    normalized_path = file_path.replace("\\", "/")
+    if not normalized_path.endswith(PYTHON_FILE_SUFFIX):
+        return False
+    return HOOK_MODULE_PATH_SEGMENT in normalized_path
+
+
+def is_constants_module(file_path: str) -> bool:
+    normalized_path = file_path.replace("\\", "/")
+    return normalized_path.endswith(CONSTANTS_MODULE_SUFFIX)
+
+
+def is_own_detector_family(file_path: str) -> bool:
+    own_module_stem = Path(__file__).stem
+    own_family_basenames = {
+        f"{own_module_stem}{PYTHON_FILE_SUFFIX}",
+        f"{own_module_stem}{CONSTANTS_MODULE_SUFFIX}",
+        f"{TEST_MODULE_PREFIX}{own_module_stem}{PYTHON_FILE_SUFFIX}",
+    }
+    normalized_path = file_path.replace("\\", "/")
+    edited_basename = normalized_path.rsplit("/", 1)[-1]
+    return edited_basename in own_family_basenames
+
+
+def detects_only_path_shape(content: str) -> bool:
+    separator_class_pattern = re.compile(PATH_SEPARATOR_CLASS_PATTERN)
+    return bool(separator_class_pattern.search(content))
+
+
+def claims_output_key_trigger(content: str) -> bool:
+    overstated_phrase_pattern = re.compile(OVERSTATED_OUTPUT_KEY_PHRASE_PATTERN, re.IGNORECASE)
+    return bool(overstated_phrase_pattern.search(content))
+
+
+def content_has_violation(content: str, file_path: str) -> bool:
+    if is_own_detector_family(file_path):
+        return False
+    if not claims_output_key_trigger(content):
+        return False
+    if is_constants_module(file_path):
+        return True
+    return detects_only_path_shape(content)
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    if tool_name not in (WRITE_TOOL_NAME, EDIT_TOOL_NAME):
+        sys.exit(0)
+
+    all_tool_input = hook_input.get("tool_input", {})
+    if not isinstance(all_tool_input, dict):
+        sys.exit(0)
+
+    edited_path = target_path(all_tool_input)
+    if not is_hook_python_module(edited_path):
+        sys.exit(0)
+
+    if not content_has_violation(
+        written_content(tool_name, all_tool_input), edited_path
+    ):
+        sys.exit(0)
+
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": CORRECTIVE_MESSAGE,
+        }
+    }
+    print(json.dumps(deny_payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

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()