claude-capsule-kit 3.0.0

package/hooks/pre-compact.js

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * PreCompact Hook - Session Continuity Before Context Compaction
+ *
+ * Fires right before Claude Code auto-compacts the context window.
+ * Saves a rich handoff document to capsule.db so the post-compaction
+ * session can resume with full context of what was happening.
+ *
+ * This is the most critical moment to save state — we still have
+ * full context but it's about to be wiped.
+ */
+
+import { Blink } from 'blink-query';
+import { createInterface } from 'readline';
+import { execSync } from 'child_process';
+import { getCapsuleDbPath, getCrewIdentity, crewNamespace, getProjectHash, isDisabled } from './lib/crew-detect.js';
+import { generateHandoff } from './lib/handoff-generator.js';
+
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  try {
+    const rl = createInterface({ input: process.stdin });
+    let inputJson = '';
+    for await (const line of rl) {
+      inputJson += line;
+    }
+
+    const input = JSON.parse(inputJson);
+    const sessionId = input.session_id || 'default';
+    if (isDisabled()) process.exit(0);
+
+    const projectHash = getProjectHash();
+    const crewId = getCrewIdentity();
+    const dbPath = getCapsuleDbPath();
+    const branch = getCurrentBranch();
+
+    // Generate handoff document while we still have full context
+    const handoff = generateHandoff(dbPath, sessionId, crewId, projectHash);
+
+    const blink = new Blink({ dbPath });
+
+    // Save pre-compaction handoff (tagged distinctly so session-start can find the latest)
+    blink.save({
+      namespace: crewNamespace(`session/${sessionId}/handoff`, crewId, projectHash),
+      title: `Pre-compact handoff ${sessionId}`,
+      summary: handoff,
+      type: 'SUMMARY',
+      content: {
+        sessionId,
+        teammateName: crewId?.teammate_name || null,
+        branch,
+        trigger: 'pre-compact',
+        generatedAt: Date.now()
+      },
+      tags: ['handoff', 'pre-compact', sessionId, ...(crewId ? [crewId.teammate_name] : [])]
+    });
+
+    blink.close();
+    process.exit(0);
+
+  } catch (error) {
+    // Never block compaction — fail silently
+    process.exit(0);
+  }
+}
+
+main();

package/hooks/pre-edit-analysis.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Pre-edit analysis - shows impact analysis before file modifications
+# Auto-runs before significant edits to show which files might be affected
+
+set -euo pipefail
+
+FILE_PATH="${1:-}"
+
+if [ -z "$FILE_PATH" ]; then
+    exit 0
+fi
+
+DEP_GRAPH="$HOME/.claude/dep-graph.toon"
+
+if [ ! -f "$DEP_GRAPH" ]; then
+    TOOL_RUNNER_PATH="$HOME/.claude/cck/lib/tool-runner.sh"
+
+    if [ -f "$TOOL_RUNNER_PATH" ]; then
+        source "$TOOL_RUNNER_PATH"
+        if command -v run_tool &> /dev/null; then
+            run_tool dependency-scanner --path "$(pwd)" --output "$DEP_GRAPH" &> /dev/null || true
+        fi
+    fi
+fi
+
+if [ ! -f "$DEP_GRAPH" ]; then
+    exit 0
+fi
+
+# Source TOON parser
+TOON_PARSER="$HOME/.claude/cck/lib/toon-parser.sh"
+if [ -f "$TOON_PARSER" ]; then
+    source "$TOON_PARSER"
+else
+    exit 0
+fi
+
+# Check if file exists in graph
+if ! toon_file_exists "$DEP_GRAPH" "$FILE_PATH"; then
+    exit 0
+fi
+
+IMPORTER_COUNT=$(toon_count_importers "$DEP_GRAPH" "$FILE_PATH")
+
+if [ "$IMPORTER_COUNT" -gt 0 ]; then
+    echo ""
+    echo "Impact Analysis for: $(basename "$FILE_PATH")"
+    echo "   Files that import this: $IMPORTER_COUNT"
+
+    IMPORTERS=$(toon_get_importers "$DEP_GRAPH" "$FILE_PATH" | head -5)
+
+    if [ -n "$IMPORTERS" ]; then
+        echo "   Affected files:"
+        echo "$IMPORTERS" | while read -r importer; do
+            echo "     $(basename "$importer")"
+        done
+    fi
+
+    if [ "$IMPORTER_COUNT" -gt 5 ]; then
+        echo "     ... and $((IMPORTER_COUNT - 5)) more"
+    fi
+
+    echo ""
+    echo "   Run 'run_tool impact-analysis $FILE_PATH' for full analysis"
+    echo ""
+fi
+
+exit 0

package/hooks/pre-tool-use.sh

@@ -0,0 +1,212 @@
+#!/bin/bash
+
+# Pre-Tool-Use Hook
+# 1. Warns before redundant file reads to encourage using capsule data
+# 2. Enforces Claude Capsule Kit tools for dependency analysis
+# 3. Auto-logs file access to capsule
+# Runs BEFORE each tool call
+# Claude Code passes arguments via stdin as JSON, NOT positional args
+
+set -euo pipefail
+
+# Defensive check: Ensure CWD exists (can be invalid if directory was deleted)
+if ! cd "$(pwd 2>/dev/null)" 2>/dev/null; then
+  cd "$HOME" 2>/dev/null || exit 0
+fi
+
+# CCK opt-out check
+[ -f "$PWD/.cck-disable" ] && exit 0
+
+# Read JSON from stdin (Claude Code's hook protocol)
+INPUT_JSON=$(cat)
+
+# Extract fields from JSON using python3
+TOOL_NAME=$(echo "$INPUT_JSON" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))" 2>/dev/null || echo "")
+TOOL_INPUT=$(echo "$INPUT_JSON" | python3 -c "import sys, json; import json as j; print(j.dumps(json.load(sys.stdin).get('tool_input', {})))" 2>/dev/null || echo "{}")
+
+# Task tool interception - enforce dependency tools
+if [ "$TOOL_NAME" == "Task" ]; then
+  # Extract prompt from Task tool input
+  TASK_PROMPT=$(echo "$TOOL_INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('prompt', ''))" 2>/dev/null || echo "")
+
+  if [ -n "$TASK_PROMPT" ]; then
+    # Convert to lowercase for pattern matching
+    PROMPT_LOWER=$(echo "$TASK_PROMPT" | tr '[:upper:]' '[:lower:]')
+
+    # Detect dependency-related queries
+    if echo "$PROMPT_LOWER" | grep -qE '(depend|import|require|module.*load|circular.*depend|who.*use|what.*import|find.*import)'; then
+      # Output JSON enforcement message (to stderr for informational display)
+      cat << 'EOF' >&2
+{"type":"tool-enforcement","category":"dependency-analysis","warning":"Query appears to be about code dependencies","dontUse":{"tool":"Task","reason":"inefficient","issues":["Slower: Scans files one-by-one","Limited: Cannot detect circular dependencies","Expensive: High token usage"]},"useInstead":[{"name":"query-deps","useCase":"what imports X, who uses X","command":"bash $HOME/.claude/cck/tools/query-deps/query-deps.sh <file-path>"},{"name":"impact-analysis","useCase":"what would break if I change X","command":"bash $HOME/.claude/cck/tools/impact-analysis/impact-analysis.sh <file-path>"},{"name":"find-circular","useCase":"circular dependencies","command":"bash $HOME/.claude/cck/tools/find-circular/find-circular.sh"}],"benefit":"These tools are instant and read pre-built dependency graph"}
+EOF
+    fi
+
+    # Detect file search queries
+    if echo "$PROMPT_LOWER" | grep -qE '(where.*file|find.*file|locate.*file|search.*file)' && ! echo "$PROMPT_LOWER" | grep -qE '(depend|import|require)'; then
+      # Output JSON suggestion message (to stderr for informational display)
+      cat << 'EOF' >&2
+{"type":"tool-suggestion","category":"file-search","useInstead":{"tool":"Glob","reason":"faster-and-direct","pattern":"**/*<filename>*","description":"For finding files by name pattern"}}
+EOF
+    fi
+
+    # Context-librarian suggestion for Task spawning (check for past agent findings)
+    SUBAGENT_TYPE=$(echo "$TOOL_INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('subagent_type', ''))" 2>/dev/null || echo "")
+
+    # Skip if already invoking context-librarian
+    if [ "$SUBAGENT_TYPE" != "context-librarian" ] && [ -f "$HOME/.claude/cck/state/session_subagents.log" ]; then
+      # Extract keywords from task prompt
+      KEYWORDS=$(echo "$TASK_PROMPT" | grep -oiE "(auth|database|schema|error|bug|architecture|api|routing|payment)" | head -1)
+
+      if [ -n "$KEYWORDS" ] && grep -qi "$KEYWORDS" "$HOME/.claude/cck/state/session_subagents.log" 2>/dev/null; then
+        cat << EOF >&2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 PAST AGENT FINDINGS AVAILABLE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Agent: $SUBAGENT_TYPE
+Topic: $KEYWORDS
+
+Past findings exist in subagent logs.
+
+Suggestion: Query context-librarian first:
+  Bash("$HOME/.claude/cck/tools/context-query/context-query.sh search $KEYWORDS")
+
+This checks if similar work was already done (saves 30-60s).
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+      fi
+    fi
+  fi
+
+  exit 0
+fi
+
+# Read tool monitoring and large file detection
+if [ "$TOOL_NAME" != "Read" ]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$TOOL_INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('file_path', ''))" 2>/dev/null || echo "")
+
+# Find project root via git
+PROJECT_ROOT="$PWD"
+while [ "$PROJECT_ROOT" != "/" ] && [ ! -d "$PROJECT_ROOT/.git" ]; do
+  PROJECT_ROOT=$(dirname "$PROJECT_ROOT")
+done
+[ "$PROJECT_ROOT" = "/" ] && PROJECT_ROOT="$PWD"
+
+# Check file size and block Read for large files (force progressive-reader)
+if [ -n "$FILE_PATH" ]; then
+  RESOLVED_PATH=""
+
+  # Try multiple path resolutions
+  if [ -f "$FILE_PATH" ]; then
+    RESOLVED_PATH="$FILE_PATH"
+  elif [ -f "$PROJECT_ROOT/$FILE_PATH" ]; then
+    RESOLVED_PATH="$PROJECT_ROOT/$FILE_PATH"
+  elif [ -f "$(pwd)/$FILE_PATH" ]; then
+    RESOLVED_PATH="$(pwd)/$FILE_PATH"
+  fi
+
+  if [ -n "$RESOLVED_PATH" ]; then
+    # Skip size check for images and binary files (Claude handles these natively)
+    FILE_EXT="${RESOLVED_PATH##*.}"
+    FILE_EXT_LOWER=$(echo "$FILE_EXT" | tr '[:upper:]' '[:lower:]')
+
+    case "$FILE_EXT_LOWER" in
+      jpg|jpeg|png|gif|webp|svg|bmp|ico|pdf|ipynb)
+        # Allow images, PDFs, notebooks regardless of size
+        exit 0
+        ;;
+    esac
+
+    FILE_SIZE=$(stat -f%z "$RESOLVED_PATH" 2>/dev/null || stat -c%s "$RESOLVED_PATH" 2>/dev/null || echo "0")
+    FILE_SIZE_KB=$((FILE_SIZE / 1024))
+
+    if [ "$FILE_SIZE" -gt 51200 ]; then  # 50KB threshold
+      echo "{\"decision\": \"block\", \"reason\": \"File ${FILE_SIZE_KB}KB exceeds 50KB. Use progressive-reader instead: \$HOME/.claude/bin/progressive-reader --path $FILE_PATH --list\"}"
+      exit 0
+    fi
+
+    # Context-librarian suggestion if file is in capsule
+    if [ -f "$HOME/.claude/cck/state/capsule.toon" ] && grep -q "$FILE_PATH" "$HOME/.claude/cck/state/capsule.toon" 2>/dev/null; then
+      FILE_AGE=$(grep "$FILE_PATH" "$HOME/.claude/cck/state/capsule.toon" | tail -1 | grep -oE '[0-9]+' | head -1 || echo "0")
+      FILE_AGE_MIN=$((FILE_AGE / 60))
+
+      if [ "$FILE_AGE_MIN" -lt 30 ]; then
+        FILE_BASENAME=$(basename "$FILE_PATH" .ts .js .go .py .tsx .jsx)
+        cat << EOF >&2
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 CONTEXT AVAILABLE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File: $FILE_PATH
+Status: Already read ${FILE_AGE_MIN}m ago (in capsule)
+
+Suggestion: Query context-librarian first (faster, 90% attention):
+  Bash("$HOME/.claude/cck/tools/context-query/context-query.sh search $FILE_BASENAME")
+
+This retrieves focused context and avoids re-reading ~12,000 tokens.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EOF
+      fi
+    fi
+  fi
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Tracking files
+CCK_STATE_DIR="$HOME/.claude/cck/state"
+mkdir -p "$CCK_STATE_DIR"
+RECENT_READS_LOG="$CCK_STATE_DIR/recent_reads.log"
+WARNINGS_SHOWN="$CCK_STATE_DIR/read_warnings_shown.log"
+
+# Create logs if they don't exist
+touch "$RECENT_READS_LOG"
+touch "$WARNINGS_SHOWN"
+
+# Check if we already warned about this file this session
+if grep -q "^${FILE_PATH}$" "$WARNINGS_SHOWN" 2>/dev/null; then
+  exit 0
+fi
+
+# Check if file was recently accessed
+CURRENT_TIME=$(date +%s)
+THRESHOLD=300  # 5 minutes in seconds
+
+if grep -q "^${FILE_PATH}," "$RECENT_READS_LOG" 2>/dev/null; then
+  # Get last read time
+  LAST_READ=$(grep "^${FILE_PATH}," "$RECENT_READS_LOG" | tail -1 | cut -d',' -f2)
+  TIME_SINCE=$((CURRENT_TIME - LAST_READ))
+
+  if [ $TIME_SINCE -lt $THRESHOLD ]; then
+    # Convert to human readable
+    if [ $TIME_SINCE -lt 60 ]; then
+      TIME_STR="${TIME_SINCE}s"
+    else
+      TIME_STR="$((TIME_SINCE / 60))m"
+    fi
+
+    # Show warning as JSON (to stderr so it doesn't interfere with JSON blocking output)
+    echo "{\"type\":\"read-warning\",\"file\":\"$FILE_PATH\",\"lastRead\":\"${TIME_STR} ago\",\"message\":\"File recently read - check capsule first\"}" >&2
+
+    # Mark as warned
+    echo "$FILE_PATH" >> "$WARNINGS_SHOWN"
+  fi
+fi
+
+# Record this read attempt
+echo "$FILE_PATH,$CURRENT_TIME" >> "$RECENT_READS_LOG"
+
+# Auto-log file access to capsule
+if [ -x "$HOME/.claude/cck/hooks/log-file-access.sh" ] && [ -x "$HOME/.claude/cck/hooks/log-file-access.sh" ]; then
+  # Auto-log this read operation (suppress output to avoid noise)
+  "$HOME/.claude/cck/hooks/log-file-access.sh" "$FILE_PATH" "read" > /dev/null 2>&1 || true
+fi
+
+exit 0

package/hooks/prompt-submit-memory.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# UserPromptSubmit Memory Injection
+# Injects relevant context based on user's prompt
+
+set -euo pipefail
+
+# Determine script directory for finding tools
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ "$SCRIPT_DIR" == *".claude/hooks"* ]]; then
+    PROJECT_ROOT="$(dirname "$(dirname "$SCRIPT_DIR")")"
+else
+    PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
+fi
+
+MEMORY_DIR="${CLAUDE_MEMORY_DIR:-.claude/memory}"
+TOOLS_DIR="$PROJECT_ROOT/tools/memory-graph"
+QUERY_PY="$TOOLS_DIR/lib/query.py"
+
+# Read prompt from stdin
+INPUT_JSON=$(cat)
+PROMPT=$(echo "$INPUT_JSON" | python3 -c "import sys, json; print(json.load(sys.stdin).get('prompt', ''))" 2>/dev/null || echo "")
+
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Check if memory graph exists
+if [ ! -d "$MEMORY_DIR/nodes" ] || [ ! -f "$QUERY_PY" ]; then
+    exit 0
+fi
+
+# Check if graph has nodes
+NODE_COUNT=$(python3 -c "import json; print(json.load(open('$MEMORY_DIR/graph.json')).get('node_count', 0))" 2>/dev/null || echo "0")
+if [ "$NODE_COUNT" = "0" ]; then
+    exit 0
+fi
+
+CONTEXT=""
+
+# Extract potential file paths from prompt (common extensions)
+FILE_MATCHES=$(echo "$PROMPT" | grep -oE '[a-zA-Z0-9_/.-]+\.(ts|tsx|js|jsx|py|go|rs|java|md|sh|json|yaml|yml)' | head -3 || echo "")
+
+# Search for file-related knowledge
+for FILE in $FILE_MATCHES; do
+    # Convert file path to node ID pattern
+    NODE_PATTERN=$(echo "$FILE" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]')
+
+    RESULT=$(CLAUDE_MEMORY_DIR="$MEMORY_DIR" python3 "$QUERY_PY" \
+        --memory-dir "$MEMORY_DIR" \
+        --command search \
+        --query "$FILE" \
+        --format summary \
+        --limit 2 \
+        --status active 2>/dev/null || echo "")
+
+    if [ -n "$RESULT" ]; then
+        CONTEXT="$CONTEXT$RESULT"$'\n'
+    fi
+done
+
+# Extract keywords (simple approach - words 4+ chars)
+KEYWORDS=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]' | grep -oE '\b[a-z]{4,}\b' | sort -u | head -5 || echo "")
+
+# Search for keyword matches in tags
+for KEYWORD in $KEYWORDS; do
+    RESULT=$(CLAUDE_MEMORY_DIR="$MEMORY_DIR" python3 "$QUERY_PY" \
+        --memory-dir "$MEMORY_DIR" \
+        --command tag \
+        --query "$KEYWORD" \
+        --format summary \
+        --limit 2 \
+        --status active 2>/dev/null || echo "")
+
+    if [ -n "$RESULT" ]; then
+        CONTEXT="$CONTEXT$RESULT"$'\n'
+    fi
+done
+
+# Dedupe and output
+if [ -n "$CONTEXT" ]; then
+    echo "# Relevant Memory"
+    echo ""
+    echo "$CONTEXT" | sort -u | head -10
+    echo ""
+fi
+
+exit 0

package/hooks/quality-check.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# Quality Check Hook
+# Post-response validation to ensure optimal approach was used
+# Runs AFTER Claude responds but BEFORE sending to user
+
+# This hook analyzes the response and provides improvement suggestions
+# It's a learning/reminder tool, not blocking
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "📊 QUALITY CHECK (Post-Response Validation)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+echo "Self-Assessment Checklist:"
+echo ""
+echo "1. ⚡ Parallel Tool Calls"
+echo "   ❓ Did I use parallel tool calls for independent operations?"
+echo "   💡 If reading 3+ files → Use multiple Read calls in one message"
+echo ""
+echo "2. 🤖 Sub-Agent Delegation"
+echo "   ❓ Should this task have been delegated to a sub-agent?"
+echo "   💡 Complex (>30 min) or specialized (agent dev, Labs, DB) → Delegate"
+echo ""
+echo "3. 🧠 Memory Usage"
+echo "   ❓ Did I check exploration journal for continuation work?"
+echo "   💡 'Continue/resume' keywords → Read docs/exploration/ first"
+echo ""
+echo "4. 📝 Progress Tracking"
+echo "   ❓ Did I use TodoWrite for multi-step tasks?"
+echo "   💡 3+ steps or >30 min → Track with todos"
+echo ""
+echo "5. 💾 Save Discoveries"
+echo "   ❓ Should I save important findings for future sessions?"
+echo "   💡 Discoveries are auto-saved via session handoff on session end"
+echo ""
+echo "6. 🔄 Avoid Redundancy"
+echo "   ❓ Did I re-read files I already read recently?"
+echo "   💡 Reference previous reads when possible"
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "✅ If all checked: Response quality is optimal!"
+echo "⚠️  If any unchecked: Consider improvements for next time"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+# Always continue (this is informational, not blocking)
+exit 0

package/hooks/session-end.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * SessionEnd Hook - Capsule Integration
+ *
+ * Finalizes the session by creating a session summary record in Capsule.
+ * Crew-aware: scopes to teammate namespace and writes to shared DB.
+ */
+
+import { Blink } from 'blink-query';
+import { createInterface } from 'readline';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { resolve } from 'path';
+import { execSync } from 'child_process';
+import { getCapsuleDbPath, getCrewIdentity, crewNamespace, getProjectHash, isDisabled } from './lib/crew-detect.js';
+import { generateHandoff } from './lib/handoff-generator.js';
+
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  try {
+    // Read hook input from stdin
+    const rl = createInterface({ input: process.stdin });
+    let inputJson = '';
+
+    for await (const line of rl) {
+      inputJson += line;
+    }
+
+    const input = JSON.parse(inputJson);
+    const sessionId = input.session_id || 'default';
+    if (isDisabled()) process.exit(0);
+    const projectHash = getProjectHash();
+    const currentBranch = getCurrentBranch();
+
+    // Shared DB in crew mode, local otherwise
+    const blink = new Blink({ dbPath: getCapsuleDbPath() });
+    const crewId = getCrewIdentity();
+
+    // Query session activity (from this teammate's namespace)
+    const filesNs = crewNamespace(`session/${sessionId}/files`, crewId, projectHash);
+    const agentsNs = crewNamespace(`session/${sessionId}/subagents`, crewId, projectHash);
+    const sessionFiles = blink.list(filesNs);
+    const sessionSubagents = blink.list(agentsNs);
+
+    // Create session summary
+    const teammateSuffix = crewId ? ` (${crewId.teammate_name})` : '';
+    const summary = [
+      `Session ${sessionId}${teammateSuffix}`,
+      `Files accessed: ${sessionFiles.length}`,
+      `Sub-agents used: ${sessionSubagents.length}`,
+      `Completed at: ${new Date().toISOString()}`
+    ].join(' | ');
+
+    // Save SESSION record (META = structured session metadata)
+    blink.save({
+      namespace: crewNamespace('session', crewId, projectHash),
+      title: `Session ${new Date().toISOString()}`,
+      summary,
+      type: 'META',
+      content: {
+        sessionId,
+        teammateName: crewId?.teammate_name || null,
+        branch: currentBranch,
+        filesCount: sessionFiles.length,
+        subagentsCount: sessionSubagents.length,
+        endedAt: Date.now()
+      },
+      tags: ['session', sessionId, ...(crewId ? [crewId.teammate_name] : [])]
+    });
+
+    // Generate and save handoff document (SUMMARY type for direct consumption)
+    const handoff = generateHandoff(getCapsuleDbPath(), sessionId, crewId, projectHash);
+    blink.save({
+      namespace: crewNamespace(`session/${sessionId}/handoff`, crewId, projectHash),
+      title: `Session ${sessionId} Handoff`,
+      summary: handoff,
+      type: 'SUMMARY',
+      content: {
+        sessionId,
+        teammateName: crewId?.teammate_name || null,
+        branch: currentBranch,
+        generatedAt: Date.now()
+      },
+      tags: ['handoff', sessionId, ...(crewId ? [crewId.teammate_name] : [])]
+    });
+
+    blink.close();
+
+    // Update team-state.json when in crew mode
+    if (crewId) {
+      try {
+        const profileName = crewId.profile_name || 'default';
+        const baseStateDir = resolve(homedir(), '.claude', 'crew', projectHash);
+        const profileStateDir = resolve(baseStateDir, profileName);
+
+        // Try profile-scoped path first, then legacy flat path
+        let statePath = resolve(profileStateDir, 'team-state.json');
+        if (!existsSync(statePath)) {
+          statePath = resolve(baseStateDir, 'team-state.json');
+        }
+
+        if (existsSync(statePath)) {
+          const state = JSON.parse(readFileSync(statePath, 'utf-8'));
+          if (state.teammates?.[crewId.teammate_name]) {
+            state.teammates[crewId.teammate_name].last_active = new Date().toISOString();
+            state.teammates[crewId.teammate_name].status = 'idle';
+            state.updated_at = new Date().toISOString();
+            writeFileSync(statePath, JSON.stringify(state, null, 2));
+          }
+        }
+      } catch { /* best effort */ }
+    }
+
+    // No output needed for SessionEnd
+    process.exit(0);
+
+  } catch (error) {
+    console.error(`[session-end.js] Error: ${error.message}`);
+    process.exit(0);
+  }
+}
+
+main();