@dragonflymcp/plugin 1.0.0

package/templates/hooks/pre-tool-grounding.template

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Zen Pre-Tool Grounding Hook
+#
+# This hook runs BEFORE dangerous tool operations execute.
+# It provides a safety layer to prevent destructive actions
+# when Claude may have lost context due to compaction.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (message sent to Claude via stderr)
+#
+# Installation:
+#   This hook is configured via .claude/settings.local.json
+#   and called by Claude Code's PreToolUse hook system.
+
+set -e
+
+# Configuration
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+ANCHORS_DIR="$PROJECT_ROOT/koan/anchors"
+LOG_FILE="$HEALTH_DIR/grounding.log"
+
+# Ensure directories exist
+mkdir -p "$HEALTH_DIR"
+
+# Get tool input from Claude Code
+TOOL_INPUT="${CLAUDE_TOOL_INPUT:-}"
+TOOL_NAME="${CLAUDE_TOOL_NAME:-Bash}"
+
+# Sanitize input for safe grep matching (escape special regex chars in input)
+# This prevents command injection through crafted TOOL_INPUT
+sanitize_for_grep() {
+    # Use printf to safely handle the input without eval
+    printf '%s' "$1"
+}
+
+# ============================================================================
+# DANGEROUS PATTERNS - Warn when context is degraded
+# ============================================================================
+# Note: Catastrophic patterns (rm -rf /, dd if=, mkfs, etc.) are blocked at
+# the permissions level via settings.local.json `permissions.deny` — they
+# never reach this hook. This hook adds compression-aware warnings for
+# dangerous-but-sometimes-needed patterns.
+
+DANGEROUS_PATTERNS=(
+    "rm -rf"
+    "rm -r"
+    "git reset --hard"
+    "git clean -fd"
+    "git checkout -- \."
+    "git stash drop"
+    "git branch -D"
+    "DROP TABLE"
+    "DROP DATABASE"
+    "TRUNCATE"
+    "DELETE FROM .* WHERE 1"
+    "--force"
+    "--hard"
+)
+
+# ============================================================================
+# LOGGING FUNCTION WITH ROTATION
+# ============================================================================
+
+# Rotate log if it exceeds 10MB
+rotate_log_if_needed() {
+    local max_size=10485760  # 10MB
+    if [ -f "$LOG_FILE" ]; then
+        local size=$(stat -f%z "$LOG_FILE" 2>/dev/null || stat --printf="%s" "$LOG_FILE" 2>/dev/null || echo 0)
+        if [ "$size" -gt "$max_size" ]; then
+            mv "$LOG_FILE" "${LOG_FILE}.old"
+            echo "[$TIMESTAMP] [INFO] Log rotated (exceeded 10MB)" > "$LOG_FILE"
+        fi
+    fi
+}
+
+log_event() {
+    local level="$1"
+    local message="$2"
+    rotate_log_if_needed
+    echo "[$TIMESTAMP] [$level] $message" >> "$LOG_FILE"
+}
+
+# ============================================================================
+# CHECK FUNCTIONS
+# ============================================================================
+
+check_dangerous_patterns() {
+    for pattern in "${DANGEROUS_PATTERNS[@]}"; do
+        # Use printf to safely pipe input (prevents command injection)
+        if printf '%s\n' "$TOOL_INPUT" | grep -qiE -- "$pattern"; then
+            log_event "DANGEROUS" "Dangerous pattern detected: $pattern | Command: $TOOL_INPUT"
+
+            # Check if we're in a degraded context state (SQLite)
+            local compression_count=0
+            if zen_state_available; then
+                compression_count=$(zen_checkpoint_count_by_type "pre_compact")
+            fi
+
+            if [ "$compression_count" -gt 0 ]; then
+                echo "WARNING: Dangerous operation detected after context compression." >&2
+                echo "Pattern: $pattern" >&2
+                echo "Context has been compressed $compression_count time(s) this session." >&2
+                echo "Please verify your understanding of the current state before proceeding." >&2
+                log_event "WARN" "Dangerous op after compression (count: $compression_count)"
+            fi
+            return 0
+        fi
+    done
+    return 0
+}
+
+verify_working_directory() {
+    if [ -f "$ANCHORS_DIR/directory.anchor.yaml" ]; then
+        local expected_dir=$(grep -oP 'working_directory: "\K[^"]+' "$ANCHORS_DIR/directory.anchor.yaml" 2>/dev/null || echo "")
+        local current_dir=$(pwd)
+
+        if [ -n "$expected_dir" ] && [ "$expected_dir" != "$current_dir" ]; then
+            log_event "WARN" "Directory mismatch: expected=$expected_dir current=$current_dir"
+        fi
+    fi
+}
+
+update_health_status() {
+    # Log grounding check event to SQLite
+    if zen_state_available; then
+        zen_event_log "grounding-$(date +%s)" "grounding_check" "{\"tool\":\"${TOOL_NAME}\"}" || true
+    fi
+}
+
+# ============================================================================
+# MAIN EXECUTION
+# ============================================================================
+
+main() {
+    if [ -z "$TOOL_INPUT" ]; then
+        exit 0
+    fi
+
+    check_dangerous_patterns
+    verify_working_directory
+    update_health_status
+
+    exit 0
+}
+
+main "$@"

package/templates/hooks/session-exit-checkpoint.sh.template

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Zen Session Exit Checkpoint Hook
+#
+# Creates a checkpoint when the Claude Code session ends or is about to exit.
+# Called by stop.sh when conditions warrant checkpoint creation.
+#
+# This hook captures:
+# - Current git state (branch, uncommitted files)
+# - Last commit information
+# - Restoration prompt for next session
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+TIMESTAMP=$(date -u +"%Y%m%d-%H%M%S")
+CREATED_AT=$(zen_timestamp_iso)
+CHECKPOINT_ID="chk-session-exit-${TIMESTAMP}"
+
+# Get git info
+GIT_BRANCH=$(zen_git_branch)
+LAST_COMMIT=$(zen_git_last_commit)
+UNCOMMITTED_FILES=$(zen_git_uncommitted_count)
+
+# Build JSON data for SQLite
+JSON_DATA="{\"automatic\":true,\"git_state\":{\"branch\":\"${GIT_BRANCH}\",\"last_commit\":\"${LAST_COMMIT}\",\"uncommitted_files\":${UNCOMMITTED_FILES}},\"restoration_prompt\":\"Session ended on branch ${GIT_BRANCH}. Last commit: ${LAST_COMMIT}. Uncommitted files: ${UNCOMMITTED_FILES}.\"}"
+
+# Write to SQLite
+if zen_state_available; then
+    zen_checkpoint_save "$CHECKPOINT_ID" "session-exit-${TIMESTAMP}" "session_exit" "$JSON_DATA"
+fi
+
+echo "Session checkpoint saved: $CHECKPOINT_ID"
+exit 0

package/templates/hooks/session-start.sh.template

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# Zen SessionStart Hook
+#
+# This hook runs when a Claude Code session starts.
+# It checks for available checkpoints and displays session context.
+#
+# Output goes to stdout and is shown to Claude in the transcript.
+# Use $CLAUDE_ENV_FILE to persist environment variables.
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🧘 Zen Session Started"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Check for available checkpoints (SQLite)
+CHECKPOINT_COUNT=0
+LATEST_NAME=""
+LATEST_DESC=""
+
+if zen_state_available; then
+  CHECKPOINT_COUNT=$(zen_checkpoint_count)
+  if [ "$CHECKPOINT_COUNT" -gt 0 ] 2>/dev/null; then
+    # Output: id|name|type|created_at
+    LATEST_ROW=$(zen_checkpoint_latest)
+    LATEST_NAME=$(echo "$LATEST_ROW" | cut -d'|' -f2)
+    LATEST_DESC=$(zen_checkpoint_latest_description)
+    LATEST_DESC="${LATEST_DESC:-Auto-saved checkpoint}"
+  fi
+fi
+
+if [ "$CHECKPOINT_COUNT" -gt 0 ] 2>/dev/null; then
+  echo ""
+  echo "📍 Available Checkpoints: $CHECKPOINT_COUNT"
+  echo "   Latest: $LATEST_NAME"
+  echo "   Description: $LATEST_DESC"
+  echo ""
+  echo "   💡 Use /restore to load checkpoint context"
+fi
+
+# Check health status (SQLite)
+CONTEXT_USAGE=""
+if zen_state_available; then
+  # Output: pct|zone
+  HEALTH_ROW=$(zen_health_get)
+  if [ -n "$HEALTH_ROW" ]; then
+    CONTEXT_USAGE=$(echo "$HEALTH_ROW" | cut -d'|' -f1)
+  fi
+fi
+
+if [ -n "$CONTEXT_USAGE" ] && [ "$CONTEXT_USAGE" != "0" ]; then
+  echo "📊 Context Usage: ${CONTEXT_USAGE}%"
+fi
+
+# Set environment variables for the session
+if [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "ZEN_PROJECT_ROOT=$PROJECT_ROOT" >> "$CLAUDE_ENV_FILE"
+  echo "ZEN_SESSION_START=$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$CLAUDE_ENV_FILE"
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+exit 0

package/templates/hooks/statusline.sh.template

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Zen Status Line
+#
+# Displays real-time context usage alongside Zen-specific state.
+# Called by Claude Code with JSON input on stdin.
+#
+# Output format: [Model] ctx% | checkpoints | health | workflows
+
+set -e
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Project root for Zen state files
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+# =============================================================================
+# Parse Claude Code JSON
+# =============================================================================
+
+# Model name (short form)
+MODEL=$(echo "$INPUT" | jq -r '.model.display_name // "Unknown"' 2>/dev/null | sed 's/Claude //' | sed 's/ /-/')
+
+# Context window metrics
+#
+# Token types from Claude Code:
+#   input_tokens: Fresh tokens (not from cache) in this request
+#   cache_creation_input_tokens: Tokens being cached this request
+#   cache_read_input_tokens: Tokens read from cache (still occupy context)
+#
+# Total context usage = all tokens in the window, regardless of caching
+# Caching affects cost, not context window occupancy
+#
+CONTEXT_SIZE=$(echo "$INPUT" | jq -r '.context_window.context_window_size // 200000' 2>/dev/null)
+CURRENT_USAGE=$(echo "$INPUT" | jq -r '.context_window.current_usage // empty' 2>/dev/null)
+
+if [ -n "$CURRENT_USAGE" ]; then
+    INPUT_TOKENS=$(echo "$CURRENT_USAGE" | jq -r '.input_tokens // 0')
+    CACHE_CREATE=$(echo "$CURRENT_USAGE" | jq -r '.cache_creation_input_tokens // 0')
+    CACHE_READ=$(echo "$CURRENT_USAGE" | jq -r '.cache_read_input_tokens // 0')
+
+    # Total context = all token types (caching is for cost, not context size)
+    TOTAL_TOKENS=$((INPUT_TOKENS + CACHE_CREATE + CACHE_READ))
+    CONTEXT_PCT=$((TOTAL_TOKENS * 100 / CONTEXT_SIZE))
+else
+    CONTEXT_PCT="?"
+    TOTAL_TOKENS=0
+fi
+
+# =============================================================================
+# Read Zen State (SQLite preferred, YAML fallback)
+# =============================================================================
+
+STATE_DB="$PROJECT_ROOT/koan/state/state.db"
+
+# Checkpoint count (SQLite only)
+CHECKPOINT_COUNT=0
+if command -v sqlite3 &>/dev/null && [ -f "$STATE_DB" ]; then
+    CHECKPOINT_COUNT=$(sqlite3 "$STATE_DB" "SELECT COUNT(*) FROM checkpoints;" 2>/dev/null || echo "0")
+fi
+
+# Health status (simplified) — use real context data computed below
+HEALTH_STATUS="--"
+
+# =============================================================================
+# Context Threshold Checkpoint
+# =============================================================================
+# Trigger safety checkpoint at 70% context usage
+
+THRESHOLD_FILE="$PROJECT_ROOT/koan/events/.context-threshold"
+CONTEXT_THRESHOLD=70
+
+# Only trigger if we have valid context percentage
+if [ "$CONTEXT_PCT" != "?" ] && [ "$CONTEXT_PCT" -ge "$CONTEXT_THRESHOLD" ] 2>/dev/null; then
+    # Check if we already triggered at this threshold
+    LAST_TRIGGER_PCT=0
+    if [ -f "$THRESHOLD_FILE" ]; then
+        LAST_TRIGGER_PCT=$(cat "$THRESHOLD_FILE" 2>/dev/null || echo "0")
+    fi
+
+    # Only trigger once per threshold crossing (70-75% range)
+    if [ "$LAST_TRIGGER_PCT" -lt "$CONTEXT_THRESHOLD" ] && [ "$CONTEXT_PCT" -lt 75 ]; then
+        # Record that we triggered
+        mkdir -p "$(dirname "$THRESHOLD_FILE")"
+        echo "$CONTEXT_PCT" > "$THRESHOLD_FILE"
+
+        # Save checkpoint directly via SQLite
+        if command -v sqlite3 &>/dev/null && [ -f "$STATE_DB" ]; then
+            CHECKPOINT_ID="ctx-threshold-$(date +%s)"
+            CHECKPOINT_DATA="{\"context_pct\":${CONTEXT_PCT},\"threshold\":${CONTEXT_THRESHOLD},\"tokens_used\":${TOTAL_TOKENS},\"model\":\"${MODEL}\"}"
+            sqlite3 "$STATE_DB" "INSERT OR IGNORE INTO checkpoints (id, name, type, data, created_at) VALUES ('$CHECKPOINT_ID', 'context-threshold-${CONTEXT_PCT}pct', 'context_threshold', '$CHECKPOINT_DATA', datetime('now'));" 2>/dev/null || true
+        fi
+    fi
+elif [ "$CONTEXT_PCT" != "?" ] && [ "$CONTEXT_PCT" -lt 50 ] 2>/dev/null; then
+    # Reset threshold tracking when context drops below 50%
+    rm -f "$THRESHOLD_FILE" 2>/dev/null || true
+fi
+
+# =============================================================================
+# Update Health Status with Real Context Data (SQLite preferred)
+# =============================================================================
+
+if [ "$CONTEXT_PCT" != "?" ]; then
+    # Determine zone based on actual usage
+    if [ "$CONTEXT_PCT" -lt 50 ]; then
+        ZONE="green"
+    elif [ "$CONTEXT_PCT" -lt 80 ]; then
+        ZONE="yellow"
+    else
+        ZONE="red"
+    fi
+
+    HEALTH_STATUS="$ZONE"
+
+    if command -v sqlite3 &>/dev/null && [ -f "$STATE_DB" ]; then
+        sqlite3 "$STATE_DB" "INSERT OR REPLACE INTO health (id, context_usage_percent, zone, updated_at) VALUES (1, ${CONTEXT_PCT}.0, '$ZONE', datetime('now'));" 2>/dev/null || true
+    fi
+fi
+
+# =============================================================================
+# Build Status Line
+# =============================================================================
+
+# Context indicator with visual cue
+if [ "$CONTEXT_PCT" = "?" ]; then
+    CTX_DISPLAY="ctx:?"
+elif [ "$CONTEXT_PCT" -lt 50 ]; then
+    CTX_DISPLAY="ctx:${CONTEXT_PCT}%"
+elif [ "$CONTEXT_PCT" -lt 80 ]; then
+    CTX_DISPLAY="ctx:${CONTEXT_PCT}%~"
+else
+    CTX_DISPLAY="ctx:${CONTEXT_PCT}%!"
+fi
+
+# Build output segments
+OUTPUT="[$MODEL] $CTX_DISPLAY"
+
+# Add checkpoint info if any exist
+if [ "$CHECKPOINT_COUNT" -gt 0 ]; then
+    OUTPUT="$OUTPUT | cp:$CHECKPOINT_COUNT"
+fi
+
+# Add health if available
+if [ "$HEALTH_STATUS" != "--" ]; then
+    OUTPUT="$OUTPUT | $HEALTH_STATUS"
+fi
+
+echo "$OUTPUT"

package/templates/hooks/stop.sh.template

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Zen Stop Hook
+#
+# This hook runs when Claude Code completes a response.
+# It updates health status and can trigger auto-saves.
+#
+# Environment variables available:
+# - CLAUDE_RESPONSE_TOKENS: Tokens in the response
+# - CLAUDE_TOOL_CALLS: Number of tool calls made
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+# Track session metrics in SQLite if available
+if zen_state_available; then
+  local_id="stop-$(date +%s%N)"
+  zen_event_log "$local_id" "session_interaction" "{\"tool_calls\":${CLAUDE_TOOL_CALLS:-0},\"response_tokens\":${CLAUDE_RESPONSE_TOKENS:-0}}" || true
+fi
+
+# =============================================================================
+# Session Exit Checkpoint Logic
+# =============================================================================
+# Create checkpoint if there's uncommitted work and it's been a while since last checkpoint
+
+UNCOMMITTED="$(zen_git_uncommitted_count)"
+CHECKPOINT_AGE=9999
+
+if zen_state_available; then
+  CHECKPOINT_AGE=$(zen_checkpoint_age_minutes)
+fi
+
+# Create session checkpoint if:
+# 1. There's uncommitted work AND
+# 2. It's been more than 30 minutes since last checkpoint
+if [ "$UNCOMMITTED" -gt 0 ] && [ "$CHECKPOINT_AGE" -gt 30 ]; then
+  SESSION_CHECKPOINT_SCRIPT="$PROJECT_ROOT/.claude/hooks/session-exit-checkpoint.sh"
+  if [ -x "$SESSION_CHECKPOINT_SCRIPT" ]; then
+    "$SESSION_CHECKPOINT_SCRIPT" > /dev/null 2>&1 || true
+  fi
+fi
+
+# Silent operation - don't pollute output on every response
+exit 0

package/templates/hooks/subagent-stop.sh.template

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Zen SubagentStop Hook
+#
+# This hook runs when a subagent (concept) completes execution.
+# It tracks costs via SQLite events.
+#
+# Environment variables available:
+# - CLAUDE_AGENT_NAME: Name of the subagent that stopped
+# - CLAUDE_AGENT_DURATION_MS: How long the agent ran (milliseconds)
+# - CLAUDE_AGENT_INPUT_TOKENS: Input tokens used
+# - CLAUDE_AGENT_OUTPUT_TOKENS: Output tokens used
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+# Only track concept agents
+case "$CLAUDE_AGENT_NAME" in
+  story-concept|architecture-concept|implementation-concept|quality-concept|version-concept|context-concept)
+    ;;
+  *)
+    # Not a concept agent, skip
+    exit 0
+    ;;
+esac
+
+# Extract concept name
+CONCEPT_NAME=$(echo "$CLAUDE_AGENT_NAME" | sed 's/-concept//')
+
+# Log concept completion to SQLite
+if zen_state_available; then
+  zen_event_log "concept-$(date +%s%N)" "concept_complete" "{\"concept\":\"$CONCEPT_NAME\",\"duration_ms\":${CLAUDE_AGENT_DURATION_MS:-0},\"input_tokens\":${CLAUDE_AGENT_INPUT_TOKENS:-0},\"output_tokens\":${CLAUDE_AGENT_OUTPUT_TOKENS:-0}}" || true
+fi
+
+# Output confirmation (visible in transcript)
+DURATION_SEC=$((${CLAUDE_AGENT_DURATION_MS:-0} / 1000))
+echo "Concept completed: $CONCEPT_NAME (${DURATION_SEC}s, ${CLAUDE_AGENT_INPUT_TOKENS:-0}+${CLAUDE_AGENT_OUTPUT_TOKENS:-0} tokens)"
+
+exit 0

package/templates/hooks/sync-blocked.sh.template

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# Zen Sync Blocked Hook
+#
+# Called when a synchronization rule is blocked (prerequisites not met).
+# Logs blocked events to SQLite for workflow debugging and optimization.
+#
+# Usage: sync-blocked.sh <rule-id> <reason> [blocking-condition]
+#
+# Arguments:
+#   $1 - Sync rule ID (e.g., "story-to-arch", "arch-to-impl")
+#   $2 - Reason for blocking (e.g., "prerequisite_failed", "condition_not_met")
+#   $3 - Optional: The specific condition that caused blocking
+
+set -e
+
+RULE_ID="${1:-unknown}"
+REASON="${2:-unknown}"
+BLOCKING_CONDITION="${3:-}"
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+# Log blocked event to SQLite
+if zen_state_available; then
+  zen_event_log "sync-blocked-$(date +%s%N)" "sync_blocked" "{\"rule_id\":\"$RULE_ID\",\"reason\":\"$REASON\",\"condition\":\"$BLOCKING_CONDITION\"}" || true
+fi
+
+# Rule-specific handling
+case "$RULE_ID" in
+  story-to-arch)
+    # Story not ready - might need clarification
+    ;;
+  arch-to-impl)
+    # Architecture incomplete or high risk awaiting approval
+    ;;
+  impl-to-quality*)
+    # Implementation has blockers
+    ;;
+  quality-to-version)
+    # Quality checks not passed
+    ;;
+esac
+
+# Output for hook runner
+echo "sync-blocked: $RULE_ID ($REASON)"
+exit 0

package/templates/hooks/timeout.sh.template

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Zen Timeout Hook
+#
+# Called when a concept or sync rule times out.
+# Logs timeout events and can trigger recovery actions.
+#
+# Usage: timeout.sh <source-type> <source-id> <timeout-ms>
+#
+# Arguments:
+#   $1 - Source type: "concept" or "sync"
+#   $2 - Source identifier (concept name or sync rule ID)
+#   $3 - Timeout duration in milliseconds
+
+set -e
+
+SOURCE_TYPE="${1:-unknown}"
+SOURCE_ID="${2:-unknown}"
+TIMEOUT_MS="${3:-0}"
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+# Log timeout event to SQLite
+if zen_state_available; then
+  EVENT_ID="timeout-$(date +%s%N)"
+  zen_event_log "$EVENT_ID" "timeout" "{\"source_type\":\"${SOURCE_TYPE}\",\"source_id\":\"${SOURCE_ID}\",\"timeout_ms\":${TIMEOUT_MS}}"
+fi
+
+# Source-specific timeout handling
+case "$SOURCE_TYPE" in
+  concept)
+    # Could notify user or trigger fallback
+    case "$SOURCE_ID" in
+      architecture)
+        # Architecture timeout is serious - might need simpler approach
+        ;;
+      implementation)
+        # Implementation timeout - could break into smaller chunks
+        ;;
+    esac
+    ;;
+  sync)
+    # Sync rule timeout - log for sync evaluation skip
+    ;;
+esac
+
+# Output for hook runner
+echo "timeout: $SOURCE_TYPE/$SOURCE_ID after ${TIMEOUT_MS}ms"
+exit 0

package/templates/hooks/user-prompt-submit.sh.template

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Zen UserPromptSubmit Hook
+#
+# This hook runs when the user submits a prompt.
+# It can classify intent and suggest workflows.
+#
+# Environment variables available:
+# - CLAUDE_USER_PROMPT: The user's prompt text (may be truncated)
+
+set -e
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+source "$PROJECT_ROOT/.claude/hooks/lib/common.sh"
+
+# Get prompt (handle potential truncation)
+PROMPT="${CLAUDE_USER_PROMPT:-}"
+
+# Skip if empty or very short
+if [ ${#PROMPT} -lt 5 ]; then
+  exit 0
+fi
+
+# Simple keyword-based intent classification
+# (More sophisticated classification would use the /classify command)
+INTENT="general"
+SUGGESTED_WORKFLOW=""
+
+# Check for feature/story keywords
+if echo "$PROMPT" | grep -qiE "(add|create|implement|build|new feature|add feature)"; then
+  INTENT="feature"
+  SUGGESTED_WORKFLOW="/feature"
+fi
+
+# Check for bug/fix keywords
+if echo "$PROMPT" | grep -qiE "(fix|bug|broken|error|issue|doesn't work|not working)"; then
+  INTENT="bugfix"
+  SUGGESTED_WORKFLOW="/feature (bugfix mode)"
+fi
+
+# Check for refactor keywords
+if echo "$PROMPT" | grep -qiE "(refactor|clean up|improve|optimize|reorganize)"; then
+  INTENT="refactor"
+fi
+
+# Check for review keywords
+if echo "$PROMPT" | grep -qiE "(review|check|audit|analyze|examine)"; then
+  INTENT="review"
+  SUGGESTED_WORKFLOW="/pr-review"
+fi
+
+# Check for exploration keywords
+if echo "$PROMPT" | grep -qiE "(explore|understand|how does|explain|what is)"; then
+  INTENT="exploration"
+  SUGGESTED_WORKFLOW="/explore"
+fi
+
+# Log classification to SQLite
+if zen_state_available; then
+  SAFE_PREVIEW=$(echo "$PROMPT" | head -c 100 | tr '"' "'" | tr '\n' ' ')
+  zen_event_log "route-$(date +%s)-$$" "intent_classification" "{\"intent\":\"$INTENT\",\"suggested_workflow\":\"$SUGGESTED_WORKFLOW\",\"prompt_length\":${#PROMPT},\"prompt_preview\":\"${SAFE_PREVIEW}...\"}" || true
+fi
+
+# Only output suggestion for clear workflow matches
+if [ -n "$SUGGESTED_WORKFLOW" ] && [ "$INTENT" != "general" ]; then
+  echo "Intent: $INTENT | Suggested: $SUGGESTED_WORKFLOW"
+fi
+
+exit 0