@hustle-together/api-dev-tools 3.12.3 → 3.12.16

package/.claude/hooks/completion-promise-detector.py

@@ -0,0 +1,293 @@
+#!/usr/bin/env python3
+"""
+Completion Promise Detector Hook (Ralph Wiggum Pattern)
+
+Detects when the agent outputs a completion promise signal like:
+  <promise>DONE</promise>
+  <promise>FIXED</promise>
+  <promise>REFACTORED</promise>
+  <promise>COMPLETE</promise>
+
+This enables autonomous loops to self-terminate gracefully when work is done,
+rather than relying solely on max-iterations safety nets.
+
+Hook Type: PostToolUse (monitors Bash, Write, Edit outputs)
+           Stop (allows graceful termination)
+
+References:
+- Geoffrey Huntley's Ralph Wiggum Technique: https://ghuntley.com/ralph/
+- docs/CLAUDE_CODE_BEST_PRACTICES.md - Section on autonomous loops
+
+Updated in v4.5.0:
+  - Add workflow logging for promise_emitted events
+  - Add iteration counting and max-iterations enforcement
+  - Log phase_transition events
+"""
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+# Import shared utilities for logging and iteration tracking (v4.5.0)
+try:
+    from hook_utils import (
+        log_workflow_event,
+        increment_phase_iteration,
+        get_phase_iterations
+    )
+    UTILS_AVAILABLE = True
+except ImportError:
+    UTILS_AVAILABLE = False
+
+# Completion promise patterns
+PROMISE_PATTERNS = [
+    r'<promise>(DONE|COMPLETE|FINISHED|SUCCESS)</promise>',
+    r'<promise>(FIXED|RESOLVED|SOLVED)</promise>',
+    r'<promise>(REFACTORED|CLEANED|IMPROVED)</promise>',
+    r'<promise>(TESTED|VERIFIED|VALIDATED)</promise>',
+    r'<promise>(DEPLOYED|SHIPPED|RELEASED)</promise>',
+    # Custom promises defined in state
+]
+
+# State file for tracking promises
+STATE_FILE = '.claude/completion-promises.json'
+
+
+def load_state():
+    """Load completion promise state."""
+    state_path = Path(STATE_FILE)
+    if state_path.exists():
+        try:
+            return json.loads(state_path.read_text())
+        except json.JSONDecodeError:
+            pass
+    return {
+        'active_promise': None,
+        'custom_patterns': [],
+        'history': []
+    }
+
+
+def save_state(state):
+    """Save completion promise state."""
+    state_path = Path(STATE_FILE)
+    state_path.parent.mkdir(parents=True, exist_ok=True)
+    state_path.write_text(json.dumps(state, indent=2))
+
+
+def get_all_patterns(state):
+    """Get all promise patterns including custom ones."""
+    patterns = PROMISE_PATTERNS.copy()
+    for custom in state.get('custom_patterns', []):
+        patterns.append(rf'<promise>({custom})</promise>')
+    return patterns
+
+
+def detect_promise(text, state):
+    """Detect if text contains a completion promise."""
+    if not text:
+        return None
+
+    patterns = get_all_patterns(state)
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if match:
+            return match.group(1).upper()
+    return None
+
+
+def handle_post_tool_use():
+    """Handle PostToolUse event - detect promises in tool output."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        return
+
+    tool_name = hook_input.get('tool_name', '')
+    tool_result = hook_input.get('tool_result', '')
+
+    # Only check tools that produce output
+    if tool_name not in ['Bash', 'Write', 'Edit', 'Read']:
+        return
+
+    state = load_state()
+
+    # v4.5.0: Check iteration limits for tools that indicate phase progress
+    if tool_name in ['Write', 'Edit'] and UTILS_AVAILABLE:
+        try:
+            # Detect current phase from context or state
+            current_phase = state.get('current_phase', 'unknown')
+            current_iter, max_iter, exceeded = increment_phase_iteration(current_phase)
+
+            if exceeded:
+                # Log the limit exceeded event
+                log_workflow_event("iteration_limit_exceeded", {
+                    "phase": current_phase,
+                    "current": current_iter,
+                    "limit": max_iter
+                })
+
+                print(json.dumps({
+                    'result': 'block',
+                    'message': f"""
+{'='*60}
+ MAX ITERATIONS EXCEEDED: {current_phase}
+{'='*60}
+
+Current iteration: {current_iter}
+Limit: {max_iter}
+
+The autonomous loop has exceeded the maximum iterations for this phase.
+This is a safety mechanism to prevent infinite loops.
+
+To continue:
+- Run /ralph-continue to reset and proceed
+- Or increase max_iterations in hustle-build-defaults.json
+"""
+                }))
+                return
+        except Exception:
+            pass
+
+    # Check for promise in output
+    promise = detect_promise(str(tool_result), state)
+
+    if promise:
+        # Record the promise detection
+        state['active_promise'] = promise
+        state['history'].append({
+            'promise': promise,
+            'tool': tool_name,
+            'detected_at': datetime.now().isoformat(),
+        })
+
+        # Keep only last 50 history entries
+        state['history'] = state['history'][-50:]
+        save_state(state)
+
+        # v4.5.0: Log the promise detection
+        if UTILS_AVAILABLE:
+            try:
+                log_workflow_event("promise_emitted", {
+                    "promise": promise,
+                    "tool": tool_name,
+                    "phase": state.get('current_phase', 'unknown')
+                })
+            except Exception:
+                pass
+
+        # Output notification
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n{'='*60}\n COMPLETION PROMISE DETECTED: {promise}\n{'='*60}\n\nThe autonomous loop can now terminate gracefully.\nTo continue anyway, use: /ralph-continue\n"
+        }))
+        return
+
+    # No promise detected, continue normally
+    print(json.dumps({'result': 'continue'}))
+
+
+def handle_stop():
+    """Handle Stop event - check if we should allow graceful termination."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        print(json.dumps({'result': 'continue'}))
+        return
+
+    state = load_state()
+    active_promise = state.get('active_promise')
+
+    if active_promise:
+        # Clear the active promise
+        state['active_promise'] = None
+        save_state(state)
+
+        # Allow graceful termination with summary
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n AUTONOMOUS LOOP COMPLETE \n\nCompletion promise '{active_promise}' was fulfilled.\nThe agent has signaled that the task is done.\n"
+        }))
+    else:
+        # No active promise, continue with normal stop behavior
+        print(json.dumps({'result': 'continue'}))
+
+
+def handle_user_prompt():
+    """Handle UserPromptSubmit - detect promise configuration."""
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except json.JSONDecodeError:
+        print(json.dumps({'result': 'continue'}))
+        return
+
+    prompt = hook_input.get('prompt', '').lower()
+    state = load_state()
+
+    # Check for Ralph Wiggum loop start
+    if '/ralph-loop' in prompt or '--completion-promise' in prompt:
+        # Extract custom promise if specified
+        match = re.search(r'--completion-promise\s+["\']?(\w+)["\']?', prompt, re.IGNORECASE)
+        if match:
+            custom_promise = match.group(1).upper()
+            if custom_promise not in state.get('custom_patterns', []):
+                state.setdefault('custom_patterns', []).append(custom_promise)
+                save_state(state)
+
+        print(json.dumps({
+            'result': 'continue',
+            'message': f"\n RALPH WIGGUM LOOP INITIALIZED \n\nListening for completion promises:\n- DONE, COMPLETE, FINISHED, SUCCESS\n- FIXED, RESOLVED, SOLVED\n- REFACTORED, CLEANED, IMPROVED\n- TESTED, VERIFIED, VALIDATED\n- DEPLOYED, SHIPPED, RELEASED\n{f'- {custom_promise} (custom)' if match else ''}\n\nOutput <promise>DONE</promise> when the task is complete.\n"
+        }))
+        return
+
+    # Check for continue command
+    if '/ralph-continue' in prompt:
+        state['active_promise'] = None
+        save_state(state)
+        print(json.dumps({
+            'result': 'continue',
+            'message': "Cleared active promise. Autonomous loop will continue."
+        }))
+        return
+
+    # Check for status command
+    if '/ralph-status' in prompt:
+        active = state.get('active_promise', 'None')
+        history = state.get('history', [])[-5:]
+
+        status_msg = f"\n RALPH WIGGUM STATUS \n\nActive Promise: {active}\n\nRecent History:\n"
+        for h in history:
+            status_msg += f"  - {h.get('promise')} via {h.get('tool')} at {h.get('detected_at', 'unknown')[:19]}\n"
+
+        if not history:
+            status_msg += "  (no promises detected yet)\n"
+
+        print(json.dumps({
+            'result': 'continue',
+            'message': status_msg
+        }))
+        return
+
+    print(json.dumps({'result': 'continue'}))
+
+
+def main():
+    """Main entry point - determine hook type from environment."""
+    hook_type = os.environ.get('CLAUDE_HOOK_TYPE', 'PostToolUse')
+
+    if hook_type == 'PostToolUse':
+        handle_post_tool_use()
+    elif hook_type == 'Stop':
+        handle_stop()
+    elif hook_type == 'UserPromptSubmit':
+        handle_user_prompt()
+    else:
+        # Unknown hook type, pass through
+        print(json.dumps({'result': 'continue'}))
+
+
+if __name__ == '__main__':
+    main()

package/.claude/hooks/context-capacity-warning.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""
+Hook: PostToolUse
+Purpose: Warn when context capacity reaches thresholds
+
+Monitors estimated context usage and warns at:
+- 50% capacity: Suggest summarizing or compacting
+- 75% capacity: Urgent warning, recommend /summarize
+- 90% capacity: Critical, workflow may be interrupted
+
+Uses token tracking from api-dev-state.json to estimate context size.
+
+Version: 4.0.0
+"""
+import json
+import sys
+from pathlib import Path
+from datetime import datetime
+
+# Context window sizes for Claude models (approximate)
+MODEL_CONTEXT_LIMITS = {
+    "claude-3-opus": 200000,
+    "claude-opus-4": 200000,
+    "claude-opus-4-5": 200000,
+    "claude-3-sonnet": 200000,
+    "claude-sonnet-4": 200000,
+    "claude-3-haiku": 200000,
+    "claude-3-5-sonnet": 200000,
+    "claude-3-5-haiku": 200000,
+    "default": 200000,
+}
+
+# Warning thresholds
+THRESHOLDS = {
+    "info": 0.50,      # 50% - informational
+    "warning": 0.75,   # 75% - warning
+    "critical": 0.90,  # 90% - critical
+}
+
+
+def estimate_context_usage(state: dict) -> int:
+    """
+    Estimate current context usage from state file.
+
+    Uses token tracking data to estimate how much of the
+    context window has been consumed.
+    """
+    token_usage = state.get("token_usage", {})
+    by_phase = token_usage.get("by_phase", {})
+
+    if not by_phase:
+        return 0
+
+    # Get latest phase token count
+    phase_keys = list(by_phase.keys())
+    if phase_keys:
+        latest = by_phase[phase_keys[-1]]
+        return latest.get("total_tokens", 0)
+
+    return 0
+
+
+def get_context_limit() -> int:
+    """Get the context limit for the current model."""
+    # Default to 200k for Opus/Sonnet
+    return MODEL_CONTEXT_LIMITS.get("default", 200000)
+
+
+def format_warning(level: str, usage_pct: float, tokens: int, limit: int) -> str:
+    """Format the warning message based on level."""
+    remaining = limit - tokens
+
+    if level == "info":
+        return f"""
+📊 Context Usage: {usage_pct:.0%}
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   💡 Consider running /summarize to reduce context usage.
+"""
+    elif level == "warning":
+        return f"""
+⚠️  CONTEXT WARNING: {usage_pct:.0%} CAPACITY
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   🔧 Recommended actions:
+   1. Run /summarize to compact conversation
+   2. Complete current phase before starting new work
+   3. Consider splitting remaining work into new session
+"""
+    else:  # critical
+        return f"""
+🚨 CRITICAL: CONTEXT AT {usage_pct:.0%} CAPACITY
+   Tokens used: ~{tokens:,} / {limit:,}
+   Remaining: ~{remaining:,}
+
+   ⚡ IMMEDIATE ACTION REQUIRED:
+   1. Run /summarize NOW
+   2. Complete or save current work
+   3. Context may auto-compact soon
+   4. Risk of work interruption if limit reached
+"""
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    # Read state file
+    cwd = Path.cwd()
+    state_file = cwd / ".claude" / "api-dev-state.json"
+
+    if not state_file.exists():
+        sys.exit(0)
+
+    try:
+        state = json.loads(state_file.read_text())
+    except (json.JSONDecodeError, IOError):
+        sys.exit(0)
+
+    # Estimate context usage
+    tokens_used = estimate_context_usage(state)
+    context_limit = get_context_limit()
+    usage_pct = tokens_used / context_limit if context_limit > 0 else 0
+
+    # Check if we've already warned at this level
+    capacity_state = state.get("capacity_warnings", {})
+    last_warning_level = capacity_state.get("last_level", "")
+
+    # Determine warning level
+    warning_level = None
+    if usage_pct >= THRESHOLDS["critical"]:
+        warning_level = "critical"
+    elif usage_pct >= THRESHOLDS["warning"]:
+        warning_level = "warning"
+    elif usage_pct >= THRESHOLDS["info"]:
+        warning_level = "info"
+
+    # Only warn if level has increased
+    level_order = {"": 0, "info": 1, "warning": 2, "critical": 3}
+    should_warn = (
+        warning_level and
+        level_order.get(warning_level, 0) > level_order.get(last_warning_level, 0)
+    )
+
+    if should_warn:
+        # Output warning
+        warning_msg = format_warning(warning_level, usage_pct, tokens_used, context_limit)
+        print(warning_msg, file=sys.stderr)
+
+        # Update state to track warning
+        state["capacity_warnings"] = {
+            "last_level": warning_level,
+            "last_warning_at": datetime.now().isoformat(),
+            "tokens_at_warning": tokens_used,
+        }
+
+        try:
+            state_file.write_text(json.dumps(state, indent=2))
+        except IOError:
+            pass
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/detect-interruption.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+Hook: SessionStart
+Purpose: Detect and prompt for interrupted workflows
+
+This hook runs at session start and checks if there are any
+in-progress workflows that were interrupted. If found, it injects
+a prompt asking the user if they want to resume.
+
+Added in v3.6.7 for session continuation support.
+
+Returns:
+  - JSON with additionalContext about interrupted workflows
+"""
+import json
+import sys
+import os
+from datetime import datetime
+from pathlib import Path
+
+STATE_FILE = Path(__file__).parent.parent / "api-dev-state.json"
+
+
+def get_interrupted_workflows(state):
+    """Find all workflows that are in_progress but not active."""
+    interrupted = []
+
+    # New format (v3.6.7+): check endpoints object
+    if "endpoints" in state:
+        active = state.get("active_endpoint")
+        for endpoint_name, endpoint_data in state["endpoints"].items():
+            status = endpoint_data.get("status", "not_started")
+            if status == "in_progress" and endpoint_name != active:
+                # Find the current phase
+                phases = endpoint_data.get("phases", {})
+                current_phase = None
+                for phase_name, phase_data in phases.items():
+                    if phase_data.get("status") == "in_progress":
+                        current_phase = phase_name
+                        break
+
+                interrupted.append({
+                    "endpoint": endpoint_name,
+                    "status": status,
+                    "current_phase": current_phase,
+                    "started_at": endpoint_data.get("started_at"),
+                    "interrupted_at": endpoint_data.get("session", {}).get("interrupted_at"),
+                    "interrupted_phase": endpoint_data.get("session", {}).get("interrupted_phase")
+                })
+
+        # Also check if active endpoint is not fully started
+        if active and active in state["endpoints"]:
+            active_data = state["endpoints"][active]
+            session = active_data.get("session", {})
+            if session.get("interrupted_at"):
+                # Active endpoint was previously interrupted
+                interrupted.insert(0, {
+                    "endpoint": active,
+                    "status": active_data.get("status"),
+                    "current_phase": session.get("interrupted_phase"),
+                    "started_at": active_data.get("started_at"),
+                    "interrupted_at": session.get("interrupted_at"),
+                    "is_active": True
+                })
+
+    # Old format: single endpoint
+    elif state.get("endpoint"):
+        endpoint = state.get("endpoint")
+        phases = state.get("phases", {})
+
+        # Check if any phase is in_progress
+        for phase_name, phase_data in phases.items():
+            if phase_data.get("status") == "in_progress":
+                interrupted.append({
+                    "endpoint": endpoint,
+                    "status": "in_progress",
+                    "current_phase": phase_name,
+                    "started_at": state.get("created_at"),
+                    "is_legacy": True
+                })
+                break
+
+    return interrupted
+
+
+def format_interrupted_message(interrupted):
+    """Format a user-friendly message about interrupted workflows."""
+    if not interrupted:
+        return None
+
+    lines = [
+        "",
+        "=" * 60,
+        " INTERRUPTED WORKFLOW DETECTED",
+        "=" * 60,
+        ""
+    ]
+
+    for i, workflow in enumerate(interrupted, 1):
+        endpoint = workflow["endpoint"]
+        phase = workflow.get("current_phase", "unknown")
+        started = workflow.get("started_at", "unknown")
+        interrupted_at = workflow.get("interrupted_at", "")
+
+        lines.append(f"{i}. **{endpoint}**")
+        lines.append(f"   - Phase: {phase}")
+        lines.append(f"   - Started: {started}")
+        if interrupted_at:
+            lines.append(f"   - Interrupted: {interrupted_at}")
+        lines.append("")
+
+    lines.extend([
+        "To resume an interrupted workflow, use:",
+        "  /api-continue [endpoint-name]",
+        "",
+        "Or start a new workflow with:",
+        "  /api-create [new-endpoint-name]",
+        "",
+        "=" * 60
+    ])
+
+    return "\n".join(lines)
+
+
+def main():
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        input_data = {}
+
+    # Check if state file exists
+    if not STATE_FILE.exists():
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    try:
+        state = json.loads(STATE_FILE.read_text())
+    except json.JSONDecodeError:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Find interrupted workflows
+    interrupted = get_interrupted_workflows(state)
+
+    if not interrupted:
+        print(json.dumps({"continue": True}))
+        sys.exit(0)
+
+    # Format message
+    message = format_interrupted_message(interrupted)
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": message,
+            "interruptedWorkflows": interrupted
+        }
+    }
+
+    print(json.dumps(output))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()