@arthai/agents 1.0.4 → 1.0.6

package/dist/plugins/prime/hooks/escalation-guard.sh

@@ -0,0 +1,177 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Circuit breaker for consecutive failures.
+# Tracks failed commands by error signature. After 3 failures with the same
+# signature, forces KB consultation and outputs a structured stuck report.
+#
+# Uses .claude/.escalation-state.json to persist state across tool calls.
+# stdout is injected as context.
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+STATE_FILE="$PROJECT_DIR/.claude/.escalation-state.json"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+# Extract the command and exit code
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+if [ -z "$COMMAND" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))" 2>/dev/null) || true
+fi
+
+EXIT_CODE="${CLAUDE_TOOL_RESULT_EXIT_CODE:-0}"
+
+[ -z "$COMMAND" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Skip tracking for non-failing commands and read-only commands
+# ---------------------------------------------------------------------------
+
+# Success — reset state if we had failures for this signature
+if [ "$EXIT_CODE" = "0" ]; then
+    if [ -f "$STATE_FILE" ]; then
+        # Clear state on success — the issue is resolved
+        python3 -c "
+import json, sys
+try:
+    with open('$STATE_FILE', 'r') as f:
+        state = json.load(f)
+    # Reset consecutive failures
+    state['consecutive_failures'] = 0
+    state['last_error_signature'] = ''
+    state['attempts'] = []
+    with open('$STATE_FILE', 'w') as f:
+        json.dump(state, f, indent=2)
+except:
+    pass
+" 2>/dev/null || true
+    fi
+    exit 0
+fi
+
+# Skip tracking for read-only commands (ls, cat, grep, git status, etc.)
+if echo "$COMMAND" | grep -qE '^\s*(ls|cat|head|tail|grep|rg|git\s+(status|log|diff|show|branch)|echo|pwd|which|type|file|wc)\b'; then
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Compute error signature from command + exit code
+# ---------------------------------------------------------------------------
+
+# Get the last few lines of error output (from CLAUDE_TOOL_RESULT_STDERR or infer)
+ERROR_OUTPUT="${CLAUDE_TOOL_RESULT_STDERR:-}"
+if [ -z "$ERROR_OUTPUT" ] && [ -n "${CLAUDE_TOOL_RESULT_STDOUT:-}" ]; then
+    # Sometimes errors go to stdout (e.g., npm, python)
+    ERROR_OUTPUT=$(echo "${CLAUDE_TOOL_RESULT_STDOUT:-}" | tail -5)
+fi
+
+# Compute signature: hash of (command_base + error_pattern)
+# Strip variable parts (paths, timestamps, PIDs) for stable signatures
+COMMAND_BASE=$(echo "$COMMAND" | awk '{print $1, $2}')
+ERROR_PATTERN=$(echo "$ERROR_OUTPUT" | sed 's/[0-9]\{4,\}//g; s|/[^ ]*||g' | head -3)
+SIGNATURE=$(echo "${COMMAND_BASE}:${ERROR_PATTERN}" | shasum -a 256 | cut -c1-16)
+
+# ---------------------------------------------------------------------------
+# Update state and check circuit breaker
+# ---------------------------------------------------------------------------
+
+RESULT=$(python3 -c "
+import json, sys, time, os
+
+state_file = '$STATE_FILE'
+signature = '$SIGNATURE'
+command = '''$COMMAND'''[:200]
+error = '''$ERROR_OUTPUT'''[:500]
+threshold = $CIRCUIT_BREAKER_THRESHOLD
+
+# Load or create state
+state = {'consecutive_failures': 0, 'last_error_signature': '', 'attempts': [], 'total_circuits_tripped': 0}
+try:
+    if os.path.exists(state_file):
+        with open(state_file, 'r') as f:
+            state = json.load(f)
+except:
+    pass
+
+# Check if same signature as last failure
+if state.get('last_error_signature') == signature:
+    state['consecutive_failures'] = state.get('consecutive_failures', 0) + 1
+else:
+    # New error signature — reset counter
+    state['consecutive_failures'] = 1
+    state['attempts'] = []
+
+state['last_error_signature'] = signature
+state['attempts'] = (state.get('attempts', []) + [{'command': command, 'error': error[:200], 'time': time.time()}])[-5:]
+
+# Check threshold
+tripped = state['consecutive_failures'] >= threshold
+
+if tripped:
+    state['total_circuits_tripped'] = state.get('total_circuits_tripped', 0) + 1
+
+# Save state
+os.makedirs(os.path.dirname(state_file), exist_ok=True)
+with open(state_file, 'w') as f:
+    json.dump(state, f, indent=2)
+
+# Output: tripped|count|attempts_summary
+attempts_summary = ' / '.join([a.get('command', '')[:60] for a in state.get('attempts', [])])
+print(f\"{'TRIPPED' if tripped else 'OK'}|{state['consecutive_failures']}|{attempts_summary}\")
+" 2>/dev/null) || exit 0
+
+STATUS=$(echo "$RESULT" | cut -d'|' -f1)
+COUNT=$(echo "$RESULT" | cut -d'|' -f2)
+ATTEMPTS=$(echo "$RESULT" | cut -d'|' -f3-)
+
+# ---------------------------------------------------------------------------
+# If not tripped, show warning at count 2
+# ---------------------------------------------------------------------------
+
+if [ "$STATUS" = "OK" ] && [ "$COUNT" = "2" ]; then
+    echo "ESCALATION WARNING: 2 consecutive failures with same error pattern."
+    echo "One more failure triggers the circuit breaker."
+    echo "Before retrying: check .claude/knowledge/ for known solutions."
+    exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# Circuit breaker tripped — inject structured stuck report
+# ---------------------------------------------------------------------------
+
+if [ "$STATUS" = "TRIPPED" ]; then
+    echo "CIRCUIT BREAKER TRIPPED — $COUNT consecutive failures with same error signature."
+    echo ""
+    echo "STOP. Do not attempt another fix without completing these steps:"
+    echo ""
+    echo "1. CONSULT KNOWLEDGE BASE:"
+    echo "   - Read .claude/knowledge/shared/conventions.md"
+    echo "   - Read .claude/knowledge/qa-knowledge/ (search for error keywords)"
+    echo "   - Run: git log --all --grep='fix:' --oneline -10"
+    echo ""
+    echo "2. GATHER EVIDENCE (if not already done):"
+    echo "   - Read full error output (not just the last line)"
+    echo "   - Check environment: env vars, ports (lsof), processes (ps), disk (df)"
+    echo "   - Check dependencies: node_modules, venv, Docker containers"
+    echo ""
+    echo "3. IF STILL STUCK — use this template to ask for help:"
+    echo "   ┌─────────────────────────────────────────────────────────┐"
+    echo "   │ STUCK REPORT                                           │"
+    echo "   │                                                        │"
+    echo "   │ Error: [exact error message]                           │"
+    echo "   │ Context: [what I was doing]                            │"
+    echo "   │ Attempts:                                              │"
+    echo "   │   1. [what I tried] -> [result]                        │"
+    echo "   │   2. [what I tried] -> [result]                        │"
+    echo "   │   3. [what I tried] -> [result]                        │"
+    echo "   │ Evidence: [logs, state, KB search results]             │"
+    echo "   │ What I need: [access/data/decision]                    │"
+    echo "   │ My recommendation: [option A because X]                │"
+    echo "   └─────────────────────────────────────────────────────────┘"
+    echo ""
+    echo "4. IF ON A TEAM — escalate to troubleshooter agent or ask a teammate."
+    echo "   If solo — present the stuck report to the user with options."
+    echo ""
+    echo "Previous attempts: $ATTEMPTS"
+fi
+
+exit 0

package/dist/plugins/prime/hooks/hooks.json

@@ -1,6 +1,16 @@
 {
   "hooks": {
     "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/project-setup.sh",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "",
         "hooks": [
@@ -102,6 +112,46 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/escalation-guard.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-config-change-restart-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-config-change-restart-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-server-crash-watch.sh",
+            "timeout": 15
+          }
+        ]
       }
     ],
     "SessionEnd": [
@@ -178,6 +228,16 @@
             "timeout": 5
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/pre-server-port-guard.sh",
+            "timeout": 5
+          }
+        ]
       }
     ]
   }

package/dist/plugins/prime/hooks/post-config-change-restart-reminder.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# PostToolUse hook (Edit/Write): Remind to restart after config file changes.
+# Detects modifications to docker-compose, .env, Dockerfile, nginx, and port
+# configs, then reminds the user that a /restart may be needed.
+#
+# stdout is injected as context.
+
+set -euo pipefail
+
+# Extract the file path from tool input
+FILE_PATH="${CLAUDE_TOOL_INPUT_FILE_PATH:-}"
+if [ -z "$FILE_PATH" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file_path',''))" 2>/dev/null) || true
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Check if the modified file is a config that affects running services
+# ---------------------------------------------------------------------------
+
+BASENAME=$(basename "$FILE_PATH")
+NEEDS_RESTART=false
+REASON=""
+
+case "$BASENAME" in
+    docker-compose.yml|docker-compose.yaml|docker-compose.*.yml|docker-compose.*.yaml|compose.yml|compose.yaml)
+        NEEDS_RESTART=true
+        REASON="Docker Compose config changed — containers may need rebuilding"
+        ;;
+    .env|.env.local|.env.development|.env.production)
+        NEEDS_RESTART=true
+        REASON="Environment variables changed — servers need restart to pick up new values"
+        ;;
+    Dockerfile|Dockerfile.*)
+        NEEDS_RESTART=true
+        REASON="Dockerfile changed — container needs rebuilding"
+        ;;
+    nginx.conf|nginx.*.conf)
+        NEEDS_RESTART=true
+        REASON="Nginx config changed — needs reload"
+        ;;
+    next.config.js|next.config.mjs|next.config.ts)
+        NEEDS_RESTART=true
+        REASON="Next.js config changed — dev server needs restart"
+        ;;
+    vite.config.js|vite.config.ts|vite.config.mjs)
+        NEEDS_RESTART=true
+        REASON="Vite config changed — dev server needs restart"
+        ;;
+    tsconfig.json|tsconfig.*.json)
+        NEEDS_RESTART=true
+        REASON="TypeScript config changed — dev server may need restart"
+        ;;
+    webpack.config.js|webpack.config.ts)
+        NEEDS_RESTART=true
+        REASON="Webpack config changed — dev server needs restart"
+        ;;
+    package.json)
+        NEEDS_RESTART=true
+        REASON="package.json changed — may need npm install + restart"
+        ;;
+    pyproject.toml|setup.py|setup.cfg|requirements.txt|requirements.*.txt)
+        NEEDS_RESTART=true
+        REASON="Python dependencies changed — may need pip install + restart"
+        ;;
+    Procfile|Procfile.*)
+        NEEDS_RESTART=true
+        REASON="Procfile changed — process definitions updated"
+        ;;
+esac
+
+# Also check for port-related changes in any file
+if [ "$NEEDS_RESTART" = "false" ]; then
+    # Check if the file path contains common config directories
+    if echo "$FILE_PATH" | grep -qE '(config/|conf/|\.config)'; then
+        NEEDS_RESTART=true
+        REASON="Config file modified — services may need restart"
+    fi
+fi
+
+$NEEDS_RESTART || exit 0
+
+echo "CONFIG CHANGED — $REASON. Run /restart to apply."
+
+exit 0

package/dist/plugins/prime/hooks/post-server-crash-watch.sh

@@ -0,0 +1,120 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Detect server start commands and check for crash loops.
+# After a server start is detected, waits briefly then verifies the process is
+# still running and the port is responding. Catches services that start then die.
+#
+# stdout is injected as context.
+
+set -euo pipefail
+
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+if [ -z "$COMMAND" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))" 2>/dev/null) || true
+fi
+
+[ -z "$COMMAND" ] && exit 0
+
+# Only check commands that ran successfully
+EXIT_CODE="${CLAUDE_TOOL_RESULT_EXIT_CODE:-0}"
+[ "$EXIT_CODE" != "0" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect server start commands and extract ports
+# ---------------------------------------------------------------------------
+
+PORT=""
+SERVICE=""
+
+# npm/pnpm/yarn dev/start
+if echo "$COMMAND" | grep -qE '\b(npm|pnpm|yarn)\s+run\s+(dev|start|serve)\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Node.js dev server"
+fi
+
+# next dev
+if echo "$COMMAND" | grep -qE '\bnext\s+dev\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Next.js dev server"
+fi
+
+# uvicorn
+if echo "$COMMAND" | grep -qE '\buvicorn\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-8000}"
+    SERVICE="Uvicorn"
+fi
+
+# gunicorn
+if echo "$COMMAND" | grep -qE '\bgunicorn\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-b\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    if [ -z "$PORT" ]; then
+        PORT=$(echo "$COMMAND" | grep -oE '\-\-bind\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    fi
+    PORT="${PORT:-8000}"
+    SERVICE="Gunicorn"
+fi
+
+# flask run
+if echo "$COMMAND" | grep -qE '\bflask\s+run\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-5000}"
+    SERVICE="Flask"
+fi
+
+# docker compose up
+if echo "$COMMAND" | grep -qE '\bdocker\s+compose\s+up\b'; then
+    SERVICE="Docker Compose services"
+    # For docker compose, check container status instead of port
+    sleep 8
+    down_containers=$(docker compose ps --format '{{.Name}} {{.Status}}' 2>/dev/null | grep -viE 'Up|running' | head -5) || true
+    if [ -n "$down_containers" ]; then
+        echo "CRASH DETECTED — Docker containers not healthy after 8s:"
+        echo "$down_containers"
+        echo "Check logs: docker compose logs --tail=30"
+    fi
+    exit 0
+fi
+
+# rails server
+if echo "$COMMAND" | grep -qE '\brails\s+s(erver)?\b'; then
+    PORT=$(echo "$COMMAND" | grep -oE '\-p\s+([0-9]+)' | awk '{print $2}')
+    PORT="${PORT:-3000}"
+    SERVICE="Rails server"
+fi
+
+# No server start detected
+[ -z "$SERVICE" ] && exit 0
+[ -z "$PORT" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Wait and check for crash loop
+# ---------------------------------------------------------------------------
+
+sleep 8
+
+# Check if process is still listening on the port
+pid=$(lsof -ti:"$PORT" 2>/dev/null | head -1) || true
+
+if [ -z "$pid" ]; then
+    echo "CRASH DETECTED — $SERVICE (port $PORT) is no longer running after 8s."
+    echo "The process started but has since exited. Check the terminal output for errors."
+    echo "Common causes: missing env vars, port conflict, dependency errors, syntax errors."
+    exit 0
+fi
+
+# Process is alive — try a quick HTTP health check
+http_status=$(timeout 5 curl -sf -o /dev/null -w "%{http_code}" "http://localhost:$PORT/" 2>/dev/null) || http_status="no_response"
+
+if [ "$http_status" = "no_response" ]; then
+    # Process exists but not responding to HTTP — might be starting up or non-HTTP
+    echo "$SERVICE (port $PORT): process alive (PID $pid) but not responding to HTTP yet. May still be starting."
+elif echo "$http_status" | grep -qE '^[2345]'; then
+    # Any HTTP response means the server is up
+    : # Silent success — don't spam on healthy starts
+else
+    echo "$SERVICE (port $PORT): process alive but returned HTTP $http_status."
+fi
+
+exit 0

package/dist/plugins/prime/hooks/pre-server-port-guard.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+# PreToolUse hook (Bash): Check port availability before server start commands.
+# Detects server start commands and warns if the target port is already occupied
+# by an unexpected process.
+#
+# Exit 0  = allow the command
+# Exit 2  = block the command (stdout shown as reason)
+# stdout  = injected as context (warnings)
+
+set -euo pipefail
+
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+if [ -z "$COMMAND" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))" 2>/dev/null) || true
+fi
+
+[ -z "$COMMAND" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect server start commands and extract ports
+# ---------------------------------------------------------------------------
+
+declare -a PORTS=()
+
+# npm/pnpm/yarn dev/start — default port 3000 unless --port specified
+if echo "$COMMAND" | grep -qE '\b(npm|pnpm|yarn)\s+run\s+(dev|start|serve)\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    if [ -z "$port" ]; then
+        port=$(echo "$COMMAND" | grep -oE '\bp(ort)?\s*=?\s*([0-9]{4,5})' | grep -oE '[0-9]+')
+    fi
+    PORTS+=("${port:-3000}")
+fi
+
+# next dev — default port 3000
+if echo "$COMMAND" | grep -qE '\bnext\s+dev\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-3000}")
+fi
+
+# vite — default port 5173
+if echo "$COMMAND" | grep -qE '\bvite\b' && ! echo "$COMMAND" | grep -qE '\bvite\s+build\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-5173}")
+fi
+
+# uvicorn — default port 8000
+if echo "$COMMAND" | grep -qE '\buvicorn\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-8000}")
+fi
+
+# gunicorn — default port 8000
+if echo "$COMMAND" | grep -qE '\bgunicorn\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-b\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    if [ -z "$port" ]; then
+        port=$(echo "$COMMAND" | grep -oE '\-\-bind\s+[^:]+:([0-9]+)' | grep -oE '[0-9]+$')
+    fi
+    PORTS+=("${port:-8000}")
+fi
+
+# flask run — default port 5000
+if echo "$COMMAND" | grep -qE '\bflask\s+run\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-\-port\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-5000}")
+fi
+
+# docker compose up — check compose file for ports
+if echo "$COMMAND" | grep -qE '\bdocker\s+compose\s+up\b'; then
+    PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+    if [ -f "$PROJECT_DIR/docker-compose.yml" ]; then
+        # Extract host ports from ports: mappings (e.g., "3000:3000", "5432:5432")
+        compose_ports=$(grep -oE '^\s*-\s*"?([0-9]+):' "$PROJECT_DIR/docker-compose.yml" 2>/dev/null | grep -oE '[0-9]+' | head -5) || true
+        for p in $compose_ports; do
+            PORTS+=("$p")
+        done
+    fi
+fi
+
+# rails server — default port 3000
+if echo "$COMMAND" | grep -qE '\brails\s+s(erver)?\b'; then
+    port=$(echo "$COMMAND" | grep -oE '\-p\s+([0-9]+)' | awk '{print $2}')
+    PORTS+=("${port:-3000}")
+fi
+
+# go run with -addr or explicit port
+if echo "$COMMAND" | grep -qE '\bgo\s+run\b'; then
+    port=$(echo "$COMMAND" | grep -oE ':([0-9]{4,5})' | head -1 | tr -d ':')
+    [ -n "$port" ] && PORTS+=("$port")
+fi
+
+# No server command detected
+[ ${#PORTS[@]} -eq 0 ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Check each port for conflicts
+# ---------------------------------------------------------------------------
+
+for port in "${PORTS[@]}"; do
+    [ -z "$port" ] && continue
+
+    pid=$(lsof -ti:"$port" 2>/dev/null | head -1) || true
+    if [ -n "$pid" ]; then
+        proc_name=$(ps -p "$pid" -o comm= 2>/dev/null) || proc_name="unknown"
+        echo "PORT CONFLICT — port $port is already in use by $proc_name (PID $pid)."
+        echo "Kill it first: lsof -ti:$port | xargs kill -9"
+        echo "Or use a different port."
+    fi
+done
+
+exit 0

package/dist/plugins/prime/hooks/project-setup.sh

@@ -0,0 +1,109 @@
+#!/bin/bash
+# hooks/project-setup.sh — SessionStart hook: first-run project setup for marketplace installs.
+#
+# Runs on every SessionStart. Checks for marker file .claude/.toolkit-setup-done.
+# If missing (or version is stale): creates CLAUDE.md from template, injects managed block,
+# updates .gitignore with toolkit markers.
+#
+# Templates are read from ${CLAUDE_PLUGIN_ROOT}/templates/ (bundled with the plugin).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
+MARKER_FILE="$PROJECT_DIR/.claude/.toolkit-setup-done"
+
+# Exit silently if CLAUDE_PLUGIN_ROOT is not set (not running from a plugin context)
+if [ -z "$PLUGIN_ROOT" ]; then
+    exit 0
+fi
+
+TEMPLATES_DIR="$PLUGIN_ROOT/templates"
+TEMPLATE_CLAUDE="$TEMPLATES_DIR/CLAUDE.md.template"
+TEMPLATE_BLOCK="$TEMPLATES_DIR/CLAUDE.md.managed-block"
+
+# Exit silently if templates are not bundled
+if [ ! -f "$TEMPLATE_CLAUDE" ] || [ ! -f "$TEMPLATE_BLOCK" ]; then
+    exit 0
+fi
+
+# Read toolkit version from VERSION file (bundled alongside plugin)
+TOOLKIT_VERSION="0.0.0"
+if [ -f "$PLUGIN_ROOT/VERSION" ]; then
+    TOOLKIT_VERSION=$(cat "$PLUGIN_ROOT/VERSION" 2>/dev/null | tr -d '[:space:]' || echo "0.0.0")
+fi
+
+MANAGED_START="<!-- >>> claude-agents toolkit (DO NOT EDIT THIS BLOCK) >>> -->"
+MANAGED_END="<!-- <<< claude-agents toolkit <<< -->"
+GITIGNORE_START="# >>> claude-agents managed (DO NOT EDIT THIS BLOCK) >>>"
+
+# Check marker file — skip if current version is already set up
+if [ -f "$MARKER_FILE" ]; then
+    STORED_VERSION=$(cat "$MARKER_FILE" 2>/dev/null | tr -d '[:space:]' || echo "")
+    if [ "$STORED_VERSION" = "$TOOLKIT_VERSION" ]; then
+        exit 0
+    fi
+fi
+
+CLAUDE_MD="$PROJECT_DIR/CLAUDE.md"
+GITIGNORE="$PROJECT_DIR/.gitignore"
+
+# 1. Create CLAUDE.md from template if it doesn't exist (never overwrite existing)
+if [ ! -f "$CLAUDE_MD" ]; then
+    PROJECT_NAME=$(basename "$PROJECT_DIR")
+    sed "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" "$TEMPLATE_CLAUDE" > "$CLAUDE_MD"
+fi
+
+# 2. Inject managed block into CLAUDE.md if missing, or update if version is stale
+if [ -f "$CLAUDE_MD" ]; then
+    BLOCK_CONTENT=$(cat "$TEMPLATE_BLOCK")
+    NEW_BLOCK=$(printf '%s\n<!-- version: %s -->\n%s\n%s' \
+        "$MANAGED_START" "$TOOLKIT_VERSION" "$BLOCK_CONTENT" "$MANAGED_END")
+
+    if ! grep -qF "$MANAGED_START" "$CLAUDE_MD"; then
+        # Block missing — append it
+        printf '\n\n%s\n' "$NEW_BLOCK" >> "$CLAUDE_MD"
+    else
+        # Block exists — update if version changed
+        EXISTING_VERSION=$(grep -o '<!-- version: [^>]* -->' "$CLAUDE_MD" 2>/dev/null | head -1 | sed 's/<!-- version: //;s/ -->//' | tr -d '[:space:]' || echo "")
+        if [ "$EXISTING_VERSION" != "$TOOLKIT_VERSION" ]; then
+            # Replace block contents between markers
+            tmp=$(mktemp)
+            in_block=false
+            wrote_block=false
+            while IFS= read -r line; do
+                if echo "$line" | grep -qF "$MANAGED_START"; then
+                    in_block=true
+                    printf '%s\n' "$NEW_BLOCK" >> "$tmp"
+                    wrote_block=true
+                    continue
+                fi
+                if echo "$line" | grep -qF "$MANAGED_END"; then
+                    in_block=false
+                    continue
+                fi
+                if ! $in_block; then
+                    echo "$line" >> "$tmp"
+                fi
+            done < "$CLAUDE_MD"
+            mv "$tmp" "$CLAUDE_MD"
+        fi
+    fi
+fi
+
+# 3. Update .gitignore with toolkit marker block if missing
+if [ ! -f "$GITIGNORE" ] || ! grep -qF "$GITIGNORE_START" "$GITIGNORE" 2>/dev/null; then
+    GITIGNORE_BLOCK=$(printf '%s\n.claude/.toolkit-last-seen-sha\n.claude/.toolkit-setup-done\n.claude/.claude-agents.conf\n%s' \
+        "$GITIGNORE_START" "# <<< claude-agents managed <<<")
+    if [ ! -f "$GITIGNORE" ]; then
+        printf '%s\n' "$GITIGNORE_BLOCK" > "$GITIGNORE"
+    else
+        printf '\n\n%s\n' "$GITIGNORE_BLOCK" >> "$GITIGNORE"
+    fi
+fi
+
+# 4. Write marker file with current version
+mkdir -p "$PROJECT_DIR/.claude"
+printf '%s\n' "$TOOLKIT_VERSION" > "$MARKER_FILE"
+
+exit 0