deepwork 0.3.1__py3-none-any.whl → 0.5.1__py3-none-any.whl

deepwork/hooks/check_version.sh

@@ -0,0 +1,230 @@
+#!/bin/bash
+# check_version.sh - SessionStart hook to check Claude Code version and deepwork installation
+#
+# This hook performs two critical checks:
+# 1. Verifies that the 'deepwork' command is installed and directly invokable
+# 2. Warns users if their Claude Code version is below the minimum required
+#
+# The deepwork check is blocking (exit 2) because hooks cannot function without it.
+# The version check is informational only (exit 0) to avoid blocking sessions.
+#
+# Uses hookSpecificOutput.additionalContext to pass messages to Claude's context.
+
+# ============================================================================
+# DEEPWORK INSTALLATION CHECK (BLOCKING)
+# ============================================================================
+# This check runs on EVERY hook invocation (no re-entry guard) because if
+# deepwork is not installed, nothing else will work.
+
+check_deepwork_installed() {
+    # Run 'deepwork rules clear_queue' instead of just '--version' for double utility:
+    # 1. Verifies that the 'deepwork' command is installed and directly invokable
+    # 2. Clears any stale rules from the queue, ensuring a clean slate for the session
+    if ! deepwork rules clear_queue >/dev/null 2>&1; then
+        return 1
+    fi
+    return 0
+}
+
+print_deepwork_error() {
+    cat >&2 << 'EOF'
+
+================================================================================
+                    *** DEEPWORK NOT INSTALLED ***
+================================================================================
+
+  ERROR: The 'deepwork' command is not available or cannot be directly invoked.
+
+  DeepWork must be installed such that running 'deepwork' directly works.
+  For example, running 'deepwork rules clear_queue' should succeed.
+
+  IMPORTANT: Do NOT use 'uv run deepwork' or similar wrappers.
+  The command must be directly invokable as just 'deepwork'.
+
+  ------------------------------------------------------------------------
+  |                                                                      |
+  |   Please fix your deepwork installation before proceeding.           |
+  |                                                                      |
+  |   Installation options:                                              |
+  |     - pipx install deepwork                                          |
+  |     - pip install --user deepwork (ensure ~/.local/bin is in PATH)   |
+  |     - nix develop (if using the nix flake)                           |
+  |                                                                      |
+  ------------------------------------------------------------------------
+
+================================================================================
+
+EOF
+}
+
+output_deepwork_error_json() {
+    cat << 'EOF'
+{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"DEEPWORK INSTALLATION ERROR: The 'deepwork' command is not installed or cannot be directly invoked. DeepWork must be installed such that it can be directly invoked (e.g., 'deepwork', NOT 'uv run deepwork'). Please fix your deepwork installation before proceeding with anything else. DO NOT CONTINUE until this is resolved."},"error":"deepwork command not found - please install deepwork so it can be directly invoked"}
+EOF
+}
+
+# Check deepwork installation FIRST (before any other checks)
+if ! check_deepwork_installed; then
+    print_deepwork_error
+    output_deepwork_error_json
+    exit 2  # Blocking error - prevent session from continuing
+fi
+
+# ============================================================================
+# RE-ENTRY GUARD (for version check only)
+# ============================================================================
+# SessionStart hooks can be triggered multiple times in a session (on resume,
+# clear, etc.). We only want to show the version warning once per session to
+# avoid spamming the user. We use an environment variable to track whether
+# we've already run. Note: This relies on the parent process preserving env
+# vars across hook invocations within the same session.
+if [ -n "$DEEPWORK_VERSION_CHECK_DONE" ]; then
+    # Already checked version this session, exit silently with empty JSON
+    echo '{}'
+    exit 0
+fi
+export DEEPWORK_VERSION_CHECK_DONE=1
+
+# ============================================================================
+# MINIMUM VERSION CONFIGURATION
+# ============================================================================
+MINIMUM_VERSION="2.1.14"
+
+# ============================================================================
+# VERSION CHECK LOGIC
+# ============================================================================
+
+# Get current Claude Code version
+get_current_version() {
+    local version_output
+    version_output=$(claude --version 2>/dev/null) || return 1
+    # Extract version number (e.g., "2.1.1" from "2.1.1 (Claude Code)")
+    echo "$version_output" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+' | head -1
+}
+
+# Compare two semantic versions
+# Returns 0 if version1 >= version2, 1 otherwise
+version_gte() {
+    local version1="$1"
+    local version2="$2"
+
+    # Split versions into components
+    local v1_major v1_minor v1_patch
+    local v2_major v2_minor v2_patch
+
+    IFS='.' read -r v1_major v1_minor v1_patch <<< "$version1"
+    IFS='.' read -r v2_major v2_minor v2_patch <<< "$version2"
+
+    # Default to 0 if component is missing
+    v1_major=${v1_major:-0}
+    v1_minor=${v1_minor:-0}
+    v1_patch=${v1_patch:-0}
+    v2_major=${v2_major:-0}
+    v2_minor=${v2_minor:-0}
+    v2_patch=${v2_patch:-0}
+
+    # Compare major version
+    if [ "$v1_major" -gt "$v2_major" ]; then
+        return 0
+    elif [ "$v1_major" -lt "$v2_major" ]; then
+        return 1
+    fi
+
+    # Compare minor version
+    if [ "$v1_minor" -gt "$v2_minor" ]; then
+        return 0
+    elif [ "$v1_minor" -lt "$v2_minor" ]; then
+        return 1
+    fi
+
+    # Compare patch version
+    if [ "$v1_patch" -ge "$v2_patch" ]; then
+        return 0
+    else
+        return 1
+    fi
+}
+
+# Generate warning message
+get_warning_message() {
+    local current_version="$1"
+
+    cat << EOF
+CLAUDE CODE VERSION WARNING: Your version (${current_version}) is below the minimum recommended (${MINIMUM_VERSION}). Older versions have known bugs that may cause issues with DeepWork. RECOMMENDED: Update your version of Claude Code. TELL THE USER ABOUT THIS ISSUE LOUDLY!!!
+EOF
+}
+
+# Print visual warning to stderr for immediate user visibility
+print_stderr_warning() {
+    local current_version="$1"
+
+    cat >&2 << EOF
+
+================================================================================
+                    *** CLAUDE CODE VERSION WARNING ***
+================================================================================
+
+  Your Claude Code version: ${current_version}
+  Minimum recommended:      ${MINIMUM_VERSION}
+
+  IMPORTANT: Versions below the minimum have known bugs that may cause
+  issues with DeepWork functionality. You may experience unexpected
+  behavior, errors, or incomplete operations.
+
+  ------------------------------------------------------------------------
+  |                                                                      |
+  |   RECOMMENDED ACTION: Update your version of Claude Code             |
+  |                                                                      |
+  ------------------------------------------------------------------------
+
+================================================================================
+
+EOF
+}
+
+# Output JSON with additional context for Claude
+output_json_with_context() {
+    local context="$1"
+    # Escape special characters for JSON
+    local escaped_context
+    escaped_context=$(echo "$context" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g' | tr '\n' ' ')
+
+    cat << EOF
+{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"${escaped_context}"}}
+EOF
+}
+
+# ============================================================================
+# MAIN
+# ============================================================================
+
+main() {
+    local current_version
+    local warning_message
+
+    # Get current version (don't exit on failure)
+    current_version=$(get_current_version) || current_version=""
+
+    if [ -z "$current_version" ]; then
+        # Could not determine version, output empty JSON and exit
+        echo '{}'
+        exit 0
+    fi
+
+    # Check if current version is below minimum
+    if ! version_gte "$current_version" "$MINIMUM_VERSION"; then
+        # Print visual warning to stderr
+        print_stderr_warning "$current_version"
+
+        # Output JSON with context for Claude
+        warning_message=$(get_warning_message "$current_version")
+        output_json_with_context "$warning_message"
+    else
+        # Version is OK, output empty JSON
+        echo '{}'
+    fi
+
+    exit 0
+}
+
+main "$@"

deepwork/hooks/claude_hook.sh

@@ -6,14 +6,13 @@
 # and work on any supported platform.
 #
 # Usage:
-#   claude_hook.sh <python_hook_module>
+#   claude_hook.sh <hook_name>
 #
 # Example:
-#   claude_hook.sh deepwork.hooks.rules_check
+#   claude_hook.sh rules_check
 #
-# The Python module should implement a main() function that:
-# 1. Calls deepwork.hooks.wrapper.run_hook() with a hook function
-# 2. The hook function receives HookInput and returns HookOutput
+# The hook is run via the deepwork CLI, which works regardless of how
+# deepwork was installed (pipx, uv, nix flake, etc.).
 #
 # Environment variables set by Claude Code:
 #   CLAUDE_PROJECT_DIR - Absolute path to project root
@@ -26,12 +25,12 @@
 
 set -e
 
-# Get the Python module to run
-PYTHON_MODULE="${1:-}"
+# Get the hook name to run
+HOOK_NAME="${1:-}"
 
-if [ -z "${PYTHON_MODULE}" ]; then
-    echo "Usage: claude_hook.sh <python_hook_module>" >&2
-    echo "Example: claude_hook.sh deepwork.hooks.rules_check" >&2
+if [ -z "${HOOK_NAME}" ]; then
+    echo "Usage: claude_hook.sh <hook_name>" >&2
+    echo "Example: claude_hook.sh rules_check" >&2
     exit 1
 fi
 
@@ -41,15 +40,12 @@ if [ ! -t 0 ]; then
     HOOK_INPUT=$(cat)
 fi
 
-# Set platform environment variable for the Python module
+# Set platform environment variable for the hook
 export DEEPWORK_HOOK_PLATFORM="claude"
 
-# Run the Python module, passing the input via stdin
-# The Python module is responsible for:
-# 1. Reading stdin (normalized by wrapper)
-# 2. Processing the hook logic
-# 3. Writing JSON to stdout
-echo "${HOOK_INPUT}" | python -m "${PYTHON_MODULE}"
+# Run the hook via deepwork CLI
+# This works regardless of how deepwork was installed (pipx, uv, nix flake, etc.)
+echo "${HOOK_INPUT}" | deepwork hook "${HOOK_NAME}"
 exit_code=$?
 
 exit ${exit_code}

deepwork/hooks/gemini_hook.sh

@@ -6,14 +6,13 @@
 # and work on any supported platform.
 #
 # Usage:
-#   gemini_hook.sh <python_hook_module>
+#   gemini_hook.sh <hook_name>
 #
 # Example:
-#   gemini_hook.sh deepwork.hooks.rules_check
+#   gemini_hook.sh rules_check
 #
-# The Python module should implement a main() function that:
-# 1. Calls deepwork.hooks.wrapper.run_hook() with a hook function
-# 2. The hook function receives HookInput and returns HookOutput
+# The hook is run via the deepwork CLI, which works regardless of how
+# deepwork was installed (pipx, uv, nix flake, etc.).
 #
 # Environment variables set by Gemini CLI:
 #   GEMINI_PROJECT_DIR - Absolute path to project root
@@ -26,12 +25,12 @@
 
 set -e
 
-# Get the Python module to run
-PYTHON_MODULE="${1:-}"
+# Get the hook name to run
+HOOK_NAME="${1:-}"
 
-if [ -z "${PYTHON_MODULE}" ]; then
-    echo "Usage: gemini_hook.sh <python_hook_module>" >&2
-    echo "Example: gemini_hook.sh deepwork.hooks.rules_check" >&2
+if [ -z "${HOOK_NAME}" ]; then
+    echo "Usage: gemini_hook.sh <hook_name>" >&2
+    echo "Example: gemini_hook.sh rules_check" >&2
     exit 1
 fi
 
@@ -41,15 +40,12 @@ if [ ! -t 0 ]; then
     HOOK_INPUT=$(cat)
 fi
 
-# Set platform environment variable for the Python module
+# Set platform environment variable for the hook
 export DEEPWORK_HOOK_PLATFORM="gemini"
 
-# Run the Python module, passing the input via stdin
-# The Python module is responsible for:
-# 1. Reading stdin (normalized by wrapper)
-# 2. Processing the hook logic
-# 3. Writing JSON to stdout
-echo "${HOOK_INPUT}" | python -m "${PYTHON_MODULE}"
+# Run the hook via deepwork CLI
+# This works regardless of how deepwork was installed (pipx, uv, nix flake, etc.)
+echo "${HOOK_INPUT}" | deepwork hook "${HOOK_NAME}"
 exit_code=$?
 
 exit ${exit_code}

deepwork/hooks/rules_check.py

@@ -6,12 +6,15 @@ It uses the wrapper system for cross-platform compatibility.
 
 Rule files are loaded from .deepwork/rules/ directory as frontmatter markdown files.
 
-Usage (via shell wrapper):
-    claude_hook.sh deepwork.hooks.rules_check
-    gemini_hook.sh deepwork.hooks.rules_check
+Usage (via shell wrapper - recommended):
+    claude_hook.sh rules_check
+    gemini_hook.sh rules_check
 
-Or directly with platform environment variable:
-    DEEPWORK_HOOK_PLATFORM=claude python -m deepwork.hooks.rules_check
+Or directly via deepwork CLI:
+    deepwork hook rules_check
+
+Or with platform environment variable:
+    DEEPWORK_HOOK_PLATFORM=claude deepwork hook rules_check
 """
 
 from __future__ import annotations
@@ -611,6 +614,26 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
             ):
                 continue
 
+            # For PROMPT rules, also skip if already QUEUED (already shown to agent).
+            # This prevents infinite loops when transcript is unavailable or promise
+            # tags haven't been written yet. The agent has already seen this rule.
+            if (
+                existing
+                and existing.status == QueueEntryStatus.QUEUED
+                and rule.action_type == ActionType.PROMPT
+            ):
+                continue
+
+            # For COMMAND rules with FAILED status, don't re-run the command.
+            # The agent has already seen the error. If they provide a promise,
+            # the after-loop logic will update the status to SKIPPED.
+            if (
+                existing
+                and existing.status == QueueEntryStatus.FAILED
+                and rule.action_type == ActionType.COMMAND
+            ):
+                continue
+
             # Create queue entry if new
             if not existing:
                 queue.create_entry(
@@ -644,10 +667,10 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
                             ),
                         )
                     else:
-                        # Command failed
-                        error_msg = format_command_errors(cmd_results)
-                        skip_hint = f"To skip, include `<promise>✓ {rule.name}</promise>` in your response.\n"
-                        command_errors.append(f"## {rule.name}\n{error_msg}{skip_hint}")
+                        # Command failed - format detailed error message
+                        error_msg = format_command_errors(cmd_results, rule_name=rule.name)
+                        skip_hint = f"\nTo skip, include `<promise>✓ {rule.name}</promise>` in your response."
+                        command_errors.append(f"{error_msg}{skip_hint}")
                         queue.update_status(
                             trigger_hash,
                             QueueEntryStatus.FAILED,
@@ -662,6 +685,26 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
                 # Collect for prompt output
                 prompt_results.append(result)
 
+    # Handle FAILED queue entries that have been promised
+    # (These rules weren't in results because evaluate_rules skips promised rules,
+    # but we need to update their queue status to SKIPPED)
+    if promised_rules:
+        promised_lower = {name.lower() for name in promised_rules}
+        for entry in queue.get_all_entries():
+            if (
+                entry.status == QueueEntryStatus.FAILED
+                and entry.rule_name.lower() in promised_lower
+            ):
+                queue.update_status(
+                    entry.trigger_hash,
+                    QueueEntryStatus.SKIPPED,
+                    ActionResult(
+                        type="command",
+                        output="Acknowledged via promise tag",
+                        exit_code=None,
+                    ),
+                )
+
     # Build response
     messages: list[str] = []
 
@@ -684,17 +727,33 @@ def rules_check_hook(hook_input: HookInput) -> HookOutput:
 
 def main() -> None:
     """Entry point for the rules check hook."""
-    # Determine platform from environment
     platform_str = os.environ.get("DEEPWORK_HOOK_PLATFORM", "claude")
     try:
         platform = Platform(platform_str)
     except ValueError:
         platform = Platform.CLAUDE
 
-    # Run the hook with the wrapper
     exit_code = run_hook(rules_check_hook, platform)
     sys.exit(exit_code)
 
 
 if __name__ == "__main__":
-    main()
+    # Wrap entry point to catch early failures (e.g., import errors in wrapper.py)
+    try:
+        main()
+    except Exception as e:
+        # Last resort error handling - output JSON manually since wrapper may be broken
+        import json
+        import traceback
+
+        error_output = {
+            "decision": "block",
+            "reason": (
+                "## Hook Script Error\n\n"
+                f"Error type: {type(e).__name__}\n"
+                f"Error: {e}\n\n"
+                f"Traceback:\n```\n{traceback.format_exc()}\n```"
+            ),
+        }
+        print(json.dumps(error_output))
+        sys.exit(0)

deepwork/hooks/wrapper.py

@@ -321,6 +321,55 @@ def write_stdout(data: str) -> None:
     print(data)
 
 
+def format_hook_error(
+    error: Exception,
+    context: str = "",
+) -> dict[str, Any]:
+    """
+    Format an error into a blocking JSON response with detailed information.
+
+    This is used when the hook script itself fails, to provide useful
+    error information to the user instead of a generic "non-blocking status code" message.
+
+    Args:
+        error: The exception that occurred
+        context: Additional context about where the error occurred
+
+    Returns:
+        Dict with decision="block" and detailed error message
+    """
+    import traceback
+
+    error_type = type(error).__name__
+    error_msg = str(error)
+    tb = traceback.format_exc()
+
+    parts = ["## Hook Script Error", ""]
+    if context:
+        parts.append(f"Context: {context}")
+    parts.append(f"Error type: {error_type}")
+    parts.append(f"Error: {error_msg}")
+    parts.append("")
+    parts.append("Traceback:")
+    parts.append(f"```\n{tb}\n```")
+
+    return {
+        "decision": "block",
+        "reason": "\n".join(parts),
+    }
+
+
+def output_hook_error(error: Exception, context: str = "") -> None:
+    """
+    Output a hook error as JSON to stdout.
+
+    Use this in exception handlers to ensure the hook always outputs
+    valid JSON even when crashing.
+    """
+    error_dict = format_hook_error(error, context)
+    print(json.dumps(error_dict))
+
+
 def run_hook(
     hook_fn: Callable[[HookInput], HookOutput],
     platform: Platform,
@@ -340,24 +389,25 @@ def run_hook(
         platform: The platform calling this hook
 
     Returns:
-        Exit code (0 for success, 2 for blocking)
+        Exit code (0 for success)
     """
-    # Read and normalize input
-    raw_input = read_stdin()
-    hook_input = normalize_input(raw_input, platform)
-
-    # Call the hook
     try:
+        # Read and normalize input
+        raw_input = read_stdin()
+        hook_input = normalize_input(raw_input, platform)
+
+        # Call the hook
         hook_output = hook_fn(hook_input)
-    except Exception as e:
-        # On error, allow the action but log
-        print(f"Hook error: {e}", file=sys.stderr)
-        hook_output = HookOutput()
 
-    # Denormalize and write output
-    output_json = denormalize_output(hook_output, platform, hook_input.event)
-    write_stdout(output_json)
+        # Denormalize and write output
+        output_json = denormalize_output(hook_output, platform, hook_input.event)
+        write_stdout(output_json)
 
-    # Always return 0 when using JSON output format
-    # The decision field in the JSON controls blocking behavior
-    return 0
+        # Always return 0 when using JSON output format
+        # The decision field in the JSON controls blocking behavior
+        return 0
+
+    except Exception as e:
+        # On any error, output a proper JSON error response
+        output_hook_error(e, context=f"Running hook {hook_fn.__name__}")
+        return 0  # Return 0 so Claude Code processes our JSON output

deepwork/schemas/doc_spec_schema.py

@@ -0,0 +1,64 @@
+"""JSON Schema definition for doc specs (document type definitions)."""
+
+from typing import Any
+
+# Schema for a single quality criterion
+QUALITY_CRITERION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["name", "description"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Short name for the quality criterion",
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Detailed description of what this criterion requires",
+        },
+    },
+    "additionalProperties": False,
+}
+
+# Schema for doc spec frontmatter
+DOC_SPEC_FRONTMATTER_SCHEMA: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "required": ["name", "description", "quality_criteria"],
+    "properties": {
+        "name": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable name for the document type",
+        },
+        "description": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Description of this document type's purpose",
+        },
+        "path_patterns": {
+            "type": "array",
+            "description": "Glob patterns for where documents of this type should be stored",
+            "items": {
+                "type": "string",
+                "minLength": 1,
+            },
+        },
+        "target_audience": {
+            "type": "string",
+            "description": "Who this document is written for",
+        },
+        "frequency": {
+            "type": "string",
+            "description": "How often this document type is produced (e.g., 'Monthly', 'Per sprint')",
+        },
+        "quality_criteria": {
+            "type": "array",
+            "description": "Quality criteria that documents of this type must meet",
+            "minItems": 1,
+            "items": QUALITY_CRITERION_SCHEMA,
+        },
+    },
+    "additionalProperties": False,
+}

deepwork/schemas/job_schema.py

@@ -161,10 +161,32 @@ JOB_SCHEMA: dict[str, Any] = {
                     },
                     "outputs": {
                         "type": "array",
-                        "description": "List of output files/directories",
+                        "description": "List of output files/directories, optionally with document type references",
                         "items": {
-                            "type": "string",
-                            "minLength": 1,
+                            "oneOf": [
+                                {
+                                    "type": "string",
+                                    "minLength": 1,
+                                    "description": "Simple output file path (backward compatible)",
+                                },
+                                {
+                                    "type": "object",
+                                    "required": ["file"],
+                                    "properties": {
+                                        "file": {
+                                            "type": "string",
+                                            "minLength": 1,
+                                            "description": "Output file path",
+                                        },
+                                        "doc_spec": {
+                                            "type": "string",
+                                            "pattern": r"^\.deepwork/doc_specs/[a-z][a-z0-9_-]*\.md$",
+                                            "description": "Path to doc spec file",
+                                        },
+                                    },
+                                    "additionalProperties": False,
+                                },
+                            ],
                         },
                     },
                     "dependencies": {