@arthai/agents 1.0.0

package/hooks/post-merge-cleanup.sh

@@ -0,0 +1,101 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Clean up fix/plan artifacts after PR merge.
+# Detects gh pr merge, git merge, or git pull (with merge) and removes
+# stale artifacts that could interfere with future work.
+#
+# Artifacts cleaned:
+#   .claude/.fix-scope-lock.json       — scope lock from /fix
+#   .claude/.fix-behavior-contract.md  — behavior contract from /fix
+#   .claude/.fix-baseline-*.txt        — test baseline snapshots from /fix
+#   .claude/.toolkit-last-seen-sha     — updated (not deleted) to current
+#
+# 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
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# ---------------------------------------------------------------------------
+# Detect merge-related commands
+# ---------------------------------------------------------------------------
+
+IS_MERGE=false
+
+# gh pr merge
+if echo "$COMMAND" | grep -qE 'gh\s+pr\s+merge'; then
+    IS_MERGE=true
+fi
+
+# git merge (not --abort)
+if echo "$COMMAND" | grep -qE 'git\s+merge\b' && ! echo "$COMMAND" | grep -q '\-\-abort'; then
+    IS_MERGE=true
+fi
+
+# git pull (often results in a merge)
+if echo "$COMMAND" | grep -qE 'git\s+pull\b'; then
+    IS_MERGE=true
+fi
+
+$IS_MERGE || exit 0
+
+# ---------------------------------------------------------------------------
+# Check tool output for success (don't clean up if merge failed)
+# ---------------------------------------------------------------------------
+
+OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"
+if [ -n "$OUTPUT" ]; then
+    # If output contains error indicators, skip cleanup
+    if echo "$OUTPUT" | grep -qiE 'error|failed|conflict|abort|rejected|denied'; then
+        exit 0
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Clean up fix artifacts
+# ---------------------------------------------------------------------------
+
+cleaned=()
+
+# Scope lock
+if [ -f "$PROJECT_DIR/.claude/.fix-scope-lock.json" ]; then
+    rm -f "$PROJECT_DIR/.claude/.fix-scope-lock.json"
+    cleaned+=("scope lock")
+fi
+
+# Behavior contract
+if [ -f "$PROJECT_DIR/.claude/.fix-behavior-contract.md" ]; then
+    rm -f "$PROJECT_DIR/.claude/.fix-behavior-contract.md"
+    cleaned+=("behavior contract")
+fi
+
+# Baseline test snapshots
+for baseline in "$PROJECT_DIR/.claude/.fix-baseline-"*.txt; do
+    if [ -f "$baseline" ]; then
+        rm -f "$baseline"
+        cleaned+=("test baseline")
+        break  # Only report once even if multiple files
+    fi
+done
+
+# Baseline summary
+if [ -f "$PROJECT_DIR/.claude/.fix-baseline-summary.txt" ]; then
+    rm -f "$PROJECT_DIR/.claude/.fix-baseline-summary.txt"
+    # Don't add to cleaned — already covered by "test baseline"
+fi
+
+# ---------------------------------------------------------------------------
+# Report what was cleaned
+# ---------------------------------------------------------------------------
+
+if [ ${#cleaned[@]} -gt 0 ]; then
+    echo "Post-merge cleanup: removed $(IFS=', '; echo "${cleaned[*]}") from previous /fix run"
+fi
+
+exit 0

package/hooks/post-test-summary.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# PostToolUse hook (Bash): Summarize test results after test runs.
+# Detects pytest, jest, vitest, playwright output and injects a compact summary.
+#
+# stdout is injected as context.
+
+set -euo pipefail
+
+# Extract the command that was run
+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
+
+# Get the tool output
+OUTPUT="${CLAUDE_TOOL_OUTPUT:-}"
+
+[ -z "$COMMAND" ] && exit 0
+[ -z "$OUTPUT" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Detect test runner and parse results
+# ---------------------------------------------------------------------------
+
+# pytest
+if echo "$COMMAND" | grep -qE '\bpytest\b|python\s+-m\s+pytest'; then
+    # Look for the summary line: "X passed, Y failed, Z errors in Ns"
+    summary_line=$(echo "$OUTPUT" | grep -oE '[0-9]+ passed|[0-9]+ failed|[0-9]+ error' | head -5) || true
+
+    if [ -n "$summary_line" ]; then
+        passed=$(echo "$summary_line" | grep -oE '[0-9]+ passed' | grep -oE '[0-9]+') || echo "0"
+        failed=$(echo "$summary_line" | grep -oE '[0-9]+ failed' | grep -oE '[0-9]+') || echo "0"
+        errors=$(echo "$summary_line" | grep -oE '[0-9]+ error' | grep -oE '[0-9]+') || echo "0"
+
+        echo "TEST SUMMARY (pytest): ${passed:-0} passed, ${failed:-0} failed, ${errors:-0} errors"
+
+        # Extract failure names (FAILED lines)
+        if [ "${failed:-0}" -gt 0 ] || [ "${errors:-0}" -gt 0 ]; then
+            echo "  Failures:"
+            echo "$OUTPUT" | grep -E '^FAILED |^ERROR ' | head -5 | while read -r line; do
+                echo "    ${line}"
+            done
+        fi
+    fi
+    exit 0
+fi
+
+# jest / vitest
+if echo "$COMMAND" | grep -qE '\bnpm\s+test\b|\bnpx\s+(jest|vitest)\b|\bvitest\b'; then
+    # Jest summary: "Test Suites: X passed, Y failed" / "Tests: X passed, Y failed"
+    suite_line=$(echo "$OUTPUT" | grep -oE 'Test Suites:.*' | head -1) || true
+    test_line=$(echo "$OUTPUT" | grep -oE 'Tests:.*' | head -1) || true
+
+    if [ -n "$suite_line" ] || [ -n "$test_line" ]; then
+        echo "TEST SUMMARY (jest/vitest):"
+        [ -n "$suite_line" ] && echo "  ${suite_line}"
+        [ -n "$test_line" ] && echo "  ${test_line}"
+
+        # Extract failed test names
+        echo "$OUTPUT" | grep -E '✕|✗|FAIL ' | head -5 | while read -r line; do
+            echo "  ${line}"
+        done
+    fi
+    exit 0
+fi
+
+# playwright
+if echo "$COMMAND" | grep -qE '\bplaywright\s+test\b'; then
+    # Playwright summary: "X passed" / "X failed"
+    summary=$(echo "$OUTPUT" | grep -oE '[0-9]+ passed|[0-9]+ failed|[0-9]+ skipped' | head -5) || true
+
+    if [ -n "$summary" ]; then
+        passed=$(echo "$summary" | grep -oE '[0-9]+ passed' | grep -oE '[0-9]+') || echo "0"
+        failed=$(echo "$summary" | grep -oE '[0-9]+ failed' | grep -oE '[0-9]+') || echo "0"
+
+        echo "TEST SUMMARY (playwright): ${passed:-0} passed, ${failed:-0} failed"
+
+        if [ "${failed:-0}" -gt 0 ]; then
+            echo "  Failed tests:"
+            echo "$OUTPUT" | grep -E '✘|FAILED|failed' | head -5 | while read -r line; do
+                echo "    ${line}"
+            done
+        fi
+    fi
+    exit 0
+fi
+
+# Lint checks (ruff, eslint)
+if echo "$COMMAND" | grep -qE '\bruff\s+check\b'; then
+    error_count=$(echo "$OUTPUT" | grep -cE '^\S+:\d+:\d+:' 2>/dev/null) || echo "0"
+    if [ "${error_count:-0}" -gt 0 ]; then
+        echo "LINT SUMMARY (ruff): ${error_count} issues found"
+        # Show first 3 errors
+        echo "$OUTPUT" | grep -E '^\S+:\d+:\d+:' | head -3 | while read -r line; do
+            echo "  ${line}"
+        done
+        [ "$error_count" -gt 3 ] && echo "  ... and $((error_count - 3)) more"
+    fi
+    exit 0
+fi
+
+# TypeScript type check
+if echo "$COMMAND" | grep -qE '\btsc\s+--noEmit\b'; then
+    error_count=$(echo "$OUTPUT" | grep -cE '^.+\(\d+,\d+\): error' 2>/dev/null) || echo "0"
+    if [ "${error_count:-0}" -gt 0 ]; then
+        echo "TYPE CHECK SUMMARY (tsc): ${error_count} type errors"
+        echo "$OUTPUT" | grep -E '^.+\(\d+,\d+\): error' | head -3 | while read -r line; do
+            echo "  ${line}"
+        done
+        [ "$error_count" -gt 3 ] && echo "  ... and $((error_count - 3)) more"
+    fi
+    exit 0
+fi
+
+exit 0

package/hooks/pre-bash-guard.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# PreToolUse hook (Bash): Guard rails for dangerous commands.
+# Blocks known-destructive operations, warns on risky ones.
+#
+# Exit 0  = allow the command
+# Exit 2  = block the command (stdout shown as reason)
+# stdout  = injected as context (warnings)
+#
+# Reads CLAUDE.md "Critical Rules" section for project-specific guards.
+
+set -euo pipefail
+
+# The tool input is JSON — extract the command field
+COMMAND="${CLAUDE_TOOL_INPUT_COMMAND:-}"
+
+# If no command available, try parsing from CLAUDE_TOOL_INPUT JSON
+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
+
+# Nothing to check
+[ -z "$COMMAND" ] && exit 0
+
+# ---------------------------------------------------------------------------
+# Hard blocks (exit 2 = block the tool call)
+# ---------------------------------------------------------------------------
+
+# Block: railway up (uploads untracked files — known to cause crashes)
+if echo "$COMMAND" | grep -qE '\brailway\s+up\b'; then
+    echo "⛔ BLOCKED: 'railway up' uploads untracked files and can crash services."
+    echo "Use 'git push' to deploy via Railway's auto-deploy instead."
+    exit 2
+fi
+
+# Block: git push directly to main/master (should use PR)
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*\b(main|master)\b' && ! echo "$COMMAND" | grep -q '\-\-dry-run'; then
+    # Allow if pushing a branch that happens to contain "main" in the name
+    if echo "$COMMAND" | grep -qE 'git\s+push\s+(origin\s+)?(main|master)\s*$'; then
+        echo "⛔ BLOCKED: Never push directly to main. Create a PR instead."
+        echo "Use the /pr skill to create a pull request."
+        exit 2
+    fi
+fi
+
+# Block: git push --force to main/master
+if echo "$COMMAND" | grep -qE 'git\s+push\s+--force' || echo "$COMMAND" | grep -qE 'git\s+push\s+-f\b'; then
+    if echo "$COMMAND" | grep -qE '\b(main|master)\b'; then
+        echo "⛔ BLOCKED: Force push to main is extremely dangerous."
+        exit 2
+    fi
+fi
+
+# Warn: pip uninstall (can break environments — but sometimes needed)
+if echo "$COMMAND" | grep -qE '\bpip\s+uninstall\b'; then
+    echo "⚠️ pip uninstall can break the environment. Verify this is intentional."
+    echo "If resolving a dependency conflict, consider using a fresh virtualenv instead."
+fi
+
+# Block: rm -rf on common important directories
+if echo "$COMMAND" | grep -qE 'rm\s+-rf\s+(/|~|\$HOME|\.git|node_modules/\.\.|backend|frontend|src|app)\b'; then
+    echo "⛔ BLOCKED: Destructive rm -rf on critical directory."
+    echo "This could delete important project files. Be more specific about what to remove."
+    exit 2
+fi
+
+# Block: git reset --hard (with nuance)
+# Allow: git reset --hard HEAD (reset working tree to current commit — safe)
+# Block: git reset --hard HEAD~N, origin/main, specific SHAs (loses commits)
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+    # Allow bare "git reset --hard" or "git reset --hard HEAD" (both = reset to current)
+    if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard\s*$' || echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard\s+HEAD\s*$'; then
+        echo "⚠️ git reset --hard HEAD — this discards all uncommitted changes."
+    else
+        echo "⛔ BLOCKED: git reset --hard to a different commit discards work."
+        echo "If this is intentional, the user should run this command manually."
+        exit 2
+    fi
+fi
+
+# Block: git clean -fd on root (too broad)
+if echo "$COMMAND" | grep -qE 'git\s+clean\s+-fd\s*$'; then
+    echo "⛔ BLOCKED: git clean -fd removes all untracked files."
+    echo "This could delete user's work-in-progress files. Be more specific."
+    exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Soft warnings (exit 0, but inject context)
+# ---------------------------------------------------------------------------
+
+# Warn: ruff --fix on broad scope
+if echo "$COMMAND" | grep -qE 'ruff\s+(check\s+)?--fix\s+\.' || echo "$COMMAND" | grep -qE 'ruff\s+format\s+\.'; then
+    echo "⚠️ Broad ruff --fix/format scope. Consider targeting specific files only."
+    echo "Broad auto-fixes can introduce unrelated changes."
+fi
+
+# Warn: commands that look like they target production
+if echo "$COMMAND" | grep -qiE '(prod|production)' && ! echo "$COMMAND" | grep -qiE '(staging|test|dev|local)'; then
+    echo "⚠️ This command appears to target production. Verify this is intentional."
+    echo "DO NOT proceed without explicit user confirmation."
+fi
+
+# Warn: database operations on what looks like prod URLs
+if echo "$COMMAND" | grep -qE 'psql.*railway\.net|pg_dump.*railway\.net|DATABASE_URL.*railway\.net'; then
+    echo "⚠️ Database command targeting Railway (possibly production). Double-check the target."
+    echo "DO NOT modify production data without explicit user confirmation."
+fi
+
+# Warn: CI/CD pipeline modifications
+if echo "$COMMAND" | grep -qiE '(mv|cp|rm|edit|cat\s*>).*\.(github|gitlab|circleci|buildkite)' || \
+   echo "$COMMAND" | grep -qiE '(mv|cp|rm|edit|cat\s*>).*(Jenkinsfile|azure-pipelines|bitbucket-pipelines)'; then
+    echo "⚠️ Modifying CI/CD pipeline configuration. This affects the entire team's workflow."
+    echo "Verify this change is intentional and won't break existing pipelines."
+fi
+
+# Warn: deploy target or infrastructure config changes
+if echo "$COMMAND" | grep -qiE '(mv|cp|rm|cat\s*>).*(railway\.(json|toml)|vercel\.json|fly\.toml|Dockerfile|docker-compose|terraform|k8s|helm)'; then
+    echo "⚠️ Modifying deployment/infrastructure configuration."
+    echo "Ask before changing deploy targets, service topology, or infrastructure."
+fi
+
+# Warn: npm/pip install of new packages (could affect lock files)
+if echo "$COMMAND" | grep -qE '\b(npm|pip)\s+install\s+[a-zA-Z]' && ! echo "$COMMAND" | grep -qE '\-r\s+requirements'; then
+    echo "ℹ️ Installing new package — this will modify lock files."
+fi
+
+# ---------------------------------------------------------------------------
+# Cascade detection: if .fix-attempt-count exists and is >= 3, warn
+# ---------------------------------------------------------------------------
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+ATTEMPT_FILE="$PROJECT_DIR/.claude/.fix-attempt-count"
+if [ -f "$ATTEMPT_FILE" ]; then
+    ATTEMPTS=$(cat "$ATTEMPT_FILE" 2>/dev/null || echo "0")
+    if [ "${ATTEMPTS:-0}" -ge 3 ]; then
+        echo "🛑 CASCADE WARNING: ${ATTEMPTS} consecutive fix attempts detected."
+        echo "STOP chaining fixes. Step back and reassess the root cause from scratch."
+        echo "Read the original error, trace the code path, understand WHY before trying again."
+        echo "If this is intentional, delete .claude/.fix-attempt-count to reset."
+    fi
+fi
+
+exit 0

package/hooks/pre-edit-guard.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# PreToolUse hook (Edit, Write): Warn on edits to protected files.
+# Does NOT block — only injects warnings so Claude thinks twice.
+#
+# stdout is injected as context. Exit 0 always (warnings only).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Extract 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
+
+# Get just the filename and relative path
+filename=$(basename "$FILE_PATH")
+rel_path="${FILE_PATH#$PROJECT_DIR/}"
+
+# ---------------------------------------------------------------------------
+# Bug fix scope lock enforcement
+# ---------------------------------------------------------------------------
+# If /fix created a scope lock, enforce Fix Zone / Frozen Zone boundaries.
+# Files in the Fix Zone are allowed. Watch Zone files get a warning.
+# Frozen Zone files get a strong warning (not a hard block — hook can only warn).
+
+SCOPE_LOCK="$PROJECT_DIR/.claude/.fix-scope-lock.json"
+if [ -f "$SCOPE_LOCK" ]; then
+    # Check if the file being edited is in the fix zone
+    IN_FIX_ZONE=false
+    IN_WATCH_ZONE=false
+
+    FIX_ZONE=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('fix_zone',[])))" 2>/dev/null) || true
+    WATCH_ZONE=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('watch_zone',[])))" 2>/dev/null) || true
+    FROZEN_PATTERNS=$(python3 -c "import json; print('\n'.join(json.load(open('$SCOPE_LOCK')).get('frozen_zone_patterns',[])))" 2>/dev/null) || true
+
+    # Check fix zone
+    if [ -n "$FIX_ZONE" ]; then
+        echo "$FIX_ZONE" | while read zone_file; do
+            if [ "$rel_path" = "$zone_file" ] || echo "$rel_path" | grep -q "^$zone_file"; then
+                IN_FIX_ZONE=true
+            fi
+        done
+    fi
+
+    # Check watch zone
+    if ! $IN_FIX_ZONE && [ -n "$WATCH_ZONE" ]; then
+        echo "$WATCH_ZONE" | while read zone_file; do
+            if [ "$rel_path" = "$zone_file" ] || echo "$rel_path" | grep -q "^$zone_file"; then
+                IN_WATCH_ZONE=true
+            fi
+        done
+    fi
+
+    if $IN_FIX_ZONE; then
+        : # Allowed — in Fix Zone
+    elif $IN_WATCH_ZONE; then
+        echo "⚠️ SCOPE WARNING: ${rel_path} is in the WATCH ZONE for the current bug fix."
+        echo "This file is related to the fix but was not expected to need changes."
+        echo "Explain WHY this file needs modification before proceeding."
+    elif ! $IN_FIX_ZONE && ! $IN_WATCH_ZONE; then
+        BUG_DESC=$(python3 -c "import json; print(json.load(open('$SCOPE_LOCK')).get('bug','unknown'))" 2>/dev/null) || true
+        echo "🛑 SCOPE VIOLATION: ${rel_path} is in the FROZEN ZONE."
+        echo "Bug fix scope: ${BUG_DESC}"
+        echo "This file is NOT part of the fix and should NOT be modified."
+        echo "If you must modify it, remove .claude/.fix-scope-lock.json first and explain why the scope expanded."
+        echo "DO NOT edit this file unless the user explicitly approves the scope change."
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Protected file patterns
+# ---------------------------------------------------------------------------
+
+# Dependency lock files (modifications should be intentional)
+case "$filename" in
+    requirements.txt)
+        echo "⚠️ Protected file: ${rel_path}"
+        echo "This file defines core dependencies. Removing packages can break the project."
+        echo "Only modify if explicitly asked by the user."
+        ;;
+    package-lock.json|yarn.lock|pnpm-lock.yaml)
+        echo "⚠️ Lock file: ${rel_path}"
+        echo "Lock files should be modified via npm/yarn/pnpm install, not directly."
+        ;;
+    Cargo.lock)
+        echo "⚠️ Lock file: ${rel_path}"
+        echo "Cargo.lock should be modified via cargo commands, not directly."
+        ;;
+esac
+
+# Environment files (may contain secrets)
+case "$filename" in
+    .env|.env.local|.env.production|.env.staging)
+        echo "⚠️ Environment file: ${rel_path}"
+        echo "May contain secrets. Never commit to git. Verify changes are intentional."
+        ;;
+esac
+
+# Migration files (should not be auto-edited)
+if echo "$rel_path" | grep -qE 'migrations/versions/|alembic/versions/|prisma/migrations/'; then
+    echo "⚠️ Migration file: ${rel_path}"
+    echo "Existing migrations should not be modified. Create a new migration instead."
+fi
+
+# CI/CD config files — match against rel_path for path-based patterns, filename for simple names
+if echo "$rel_path" | grep -qE '\.github/workflows/|\.gitlab-ci\.yml|Jenkinsfile'; then
+    echo "ℹ️ Infrastructure file: ${rel_path}"
+    echo "Changes may affect CI/CD pipelines or deployments."
+fi
+case "$filename" in
+    Dockerfile|docker-compose.yml|docker-compose.yaml)
+        echo "ℹ️ Infrastructure file: ${rel_path}"
+        echo "Changes may affect container builds or service topology."
+        ;;
+esac
+
+exit 0

package/hooks/pre-task-context.sh

@@ -0,0 +1,113 @@
+#!/bin/bash
+# PreToolUse hook (Task): Inject project context when spawning agents.
+# Gives every agent a warm start with project state awareness.
+#
+# v2: Reads from session-bootstrap's project state cache when available.
+# Falls back to direct computation if cache is missing or stale (>5 min).
+#
+# stdout is injected as context into the conversation (visible to the spawned agent).
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Only act if we have a CLAUDE.md (otherwise nothing to inject)
+[ ! -f "$PROJECT_DIR/CLAUDE.md" ] && exit 0
+
+# Don't inject for explore-light or haiku agents (keep them fast/cheap)
+SUBAGENT_TYPE="${CLAUDE_TOOL_INPUT_SUBAGENT_TYPE:-}"
+if [ -z "$SUBAGENT_TYPE" ] && [ -n "${CLAUDE_TOOL_INPUT:-}" ]; then
+    SUBAGENT_TYPE=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('subagent_type',''))" 2>/dev/null) || true
+fi
+
+case "$SUBAGENT_TYPE" in
+    explore-light|Explore|explore|claude-code-guide)
+        # These are lightweight/research agents — don't add overhead
+        exit 0
+        ;;
+esac
+
+# ---------------------------------------------------------------------------
+# Try reading from project state cache (written by session-bootstrap.sh)
+# ---------------------------------------------------------------------------
+
+CACHE_FILE="$PROJECT_DIR/.claude/.project-state-cache.json"
+use_cache=false
+
+if [ -f "$CACHE_FILE" ]; then
+    # Check cache freshness (5 min = 300 seconds)
+    if [ "$(uname)" = "Darwin" ]; then
+        cache_age=$(( $(date +%s) - $(stat -f%m "$CACHE_FILE") ))
+    else
+        cache_age=$(( $(date +%s) - $(stat -c%Y "$CACHE_FILE") ))
+    fi
+    if [ "$cache_age" -lt 300 ]; then
+        use_cache=true
+    fi
+fi
+
+echo "AGENT CONTEXT (auto-injected by toolkit):"
+
+if $use_cache; then
+    # Fast path: read from cache
+    branch=$(python3 -c "import json; d=json.load(open('$CACHE_FILE')); print(d.get('branch',''))" 2>/dev/null) || true
+    uncommitted=$(python3 -c "import json; d=json.load(open('$CACHE_FILE')); print(d.get('uncommitted',0))" 2>/dev/null) || true
+    docker_status=$(python3 -c "import json; d=json.load(open('$CACHE_FILE')); print(d.get('docker_status',''))" 2>/dev/null) || true
+    alembic_status=$(python3 -c "import json; d=json.load(open('$CACHE_FILE')); print(d.get('alembic_status',''))" 2>/dev/null) || true
+    active_plan=$(python3 -c "import json; d=json.load(open('$CACHE_FILE')); print(d.get('active_plan',''))" 2>/dev/null) || true
+
+    [ -n "$branch" ] && echo "  Branch: ${branch} (${uncommitted:-0} uncommitted files)"
+    [ -n "$docker_status" ] && echo "  Docker: ${docker_status}"
+    if [ "$alembic_status" = "⚠ pending migrations" ]; then
+        echo "  ⚠ Alembic: local behind head (run 'alembic upgrade head')"
+    elif [ -n "$alembic_status" ] && [ "$alembic_status" != "✓" ]; then
+        echo "  Alembic: ${alembic_status}"
+    fi
+    [ -n "$active_plan" ] && echo "  Active plan: ${active_plan}"
+else
+    # Slow path: compute directly (backward compatible)
+
+    # Git state
+    if [ -d "$PROJECT_DIR/.git" ]; then
+        branch=$(git -C "$PROJECT_DIR" rev-parse --abbrev-ref HEAD 2>/dev/null) || true
+        uncommitted=$(git -C "$PROJECT_DIR" status --short 2>/dev/null | wc -l | tr -d ' ') || true
+        [ -n "$branch" ] && echo "  Branch: ${branch} (${uncommitted:-0} uncommitted files)"
+    fi
+
+    # Docker container status (if docker-compose exists)
+    if [ -f "$PROJECT_DIR/docker-compose.yml" ] && command -v docker &>/dev/null; then
+        running=$(docker ps --format '{{.Names}}' 2>/dev/null | tr '\n' ', ' | sed 's/,$//' ) || true
+        [ -n "$running" ] && echo "  Docker running: ${running}"
+    fi
+
+    # Alembic status (if migration dir exists)
+    for alembic_dir in "$PROJECT_DIR/backend" "$PROJECT_DIR"; do
+        if [ -f "$alembic_dir/alembic.ini" ]; then
+            for v in "$alembic_dir/.venv/bin/activate" "$PROJECT_DIR/.venv/bin/activate" "$PROJECT_DIR/venv/bin/activate"; do
+                if [ -f "$v" ]; then
+                    current=$(cd "$alembic_dir" && source "$v" && timeout 3 alembic current 2>/dev/null | head -1 | awk '{print $1}') || true
+                    head_rev=$(cd "$alembic_dir" && source "$v" && timeout 3 alembic heads 2>/dev/null | head -1 | awk '{print $1}') || true
+                    if [ -n "$current" ] && [ -n "$head_rev" ]; then
+                        if [ "$current" = "$head_rev" ]; then
+                            echo "  Alembic: up to date"
+                        else
+                            echo "  ⚠ Alembic: local behind head (run 'alembic upgrade head')"
+                        fi
+                    fi
+                    break
+                fi
+            done
+            break
+        fi
+    done
+
+    # Active plan
+    if [ -d "$PROJECT_DIR/.claude/plans" ]; then
+        plan_file=$(ls -t "$PROJECT_DIR/.claude/plans/"*.md 2>/dev/null | head -1) || true
+        if [ -n "$plan_file" ]; then
+            echo "  Active plan: $(basename "$plan_file")"
+        fi
+    fi
+fi
+
+exit 0