gitmem-mcp 0.2.0 → 1.0.1

package/hooks/scripts/auto-retrieve-hook.sh

@@ -0,0 +1,163 @@
+#!/bin/bash
+# GitMem Hooks Plugin — UserPromptSubmit Hook (Auto-Retrieve)
+#
+# Automatically searches institutional memory and injects relevant scars
+# into the agent's context before it starts working.
+#
+# Pipeline:
+#   1. Read user prompt from stdin (hook input JSON)
+#   2. Classify task type via keyword matching (<50ms)
+#   3. If retrieval needed, call quick-retrieve.js (Node module)
+#   4. Inject results as additionalContext
+#
+# Task Types (priority order):
+#   trivial        → none   (confirmations, slash cmds, short prompts)
+#   architecture   → full   (design, decisions, trade-offs)
+#   research       → full   (synthesis, comparison, analysis)
+#   content        → full   (writing, documentation)
+#   implementation → scars  (building, fixing, issue work)
+#   default        → scars  (conservative default)
+#
+# Design: fail open — if anything breaks, exit 0 (never block the user).
+#
+# Disable: GITMEM_AUTO_RETRIEVE=false
+
+set -e
+
+# Check if disabled
+if [ "$GITMEM_AUTO_RETRIEVE" = "false" ] || [ "$GITMEM_AUTO_RETRIEVE" = "0" ]; then
+    exit 0
+fi
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat -)
+
+# ============================================================================
+# Extract prompt from hook input
+# ============================================================================
+
+# Use node if available, fallback to basic extraction
+PROMPT=""
+if command -v node &>/dev/null; then
+    PROMPT=$(echo "$HOOK_INPUT" | node -e "
+        let d='';
+        process.stdin.on('data',c=>d+=c);
+        process.stdin.on('end',()=>{
+            try {
+                const j=JSON.parse(d);
+                process.stdout.write(j.prompt||'');
+            } catch(e) { }
+        });
+    " 2>/dev/null) || true
+fi
+
+# Empty or missing prompt → nothing to do
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+PROMPT_LOWER=$(echo "$PROMPT" | tr '[:upper:]' '[:lower:]')
+PROMPT_LEN=${#PROMPT}
+
+# ============================================================================
+# Task Classification (keyword matching, <50ms)
+# ============================================================================
+
+RETRIEVAL_LEVEL=""
+
+# Priority 1: Trivial — skip retrieval entirely
+if echo "$PROMPT_LOWER" | grep -qE '^(yes|no|ok|k|y|n|sure|thanks|thank you|continue|go ahead|proceed|correct|right|exactly|got it|sounds good|lgtm|looks good|done|nope|yep|yup|agreed)$'; then
+    exit 0
+elif echo "$PROMPT_LOWER" | grep -qE '^/'; then
+    exit 0
+elif echo "$PROMPT_LOWER" | grep -qE '^(closing|done for now|wrapping up|wrap up|that.s it|that.s all|gitmem)'; then
+    exit 0
+elif echo "$PROMPT_LOWER" | grep -qE '\b(fix\s+typo|typo\b|formatting\b|indent(ation)?\b|whitespace\b|lint(ing)?\b)'; then
+    exit 0
+elif [ "$PROMPT_LEN" -lt 12 ]; then
+    exit 0
+fi
+
+# Priority 2: Architecture → full retrieval
+if echo "$PROMPT_LOWER" | grep -qE '\b(architect(ure)?|design\s+(the\s+)?\w+|decide\s+(between|on|whether|how|if)|should\s+we|trade-?offs?\b|rfc\b|adr\b|system\s+design)\b'; then
+    RETRIEVAL_LEVEL="full"
+
+# Priority 3: Research → full retrieval
+elif echo "$PROMPT_LOWER" | grep -qE '\b(research\b|synthesize|synthesis\b|compare\s+(and|the|our)|contrast\b|analyze\s+(the\s+)?(options|approaches|alternatives)|evaluate\s+(frameworks|tools|approaches))\b'; then
+    RETRIEVAL_LEVEL="full"
+
+# Priority 4: Content creation → full retrieval
+elif echo "$PROMPT_LOWER" | grep -qE '\b(write\s+(a|an|the|about)|article\b|blog\s*(post)?|document\s+(the|how|what)|explain\s+(how|what|the)|guide\s+(to|for)|tutorial\b)\b'; then
+    RETRIEVAL_LEVEL="full"
+
+# Priority 5: Implementation → scars only
+elif echo "$PROMPT_LOWER" | grep -qE '\b(implement|build\b|fix\s+(the\s+)?bug|refactor|migrate\b|pickup\b|pick\s*up|create\s+(a|the)|add\s+(a|the))\b'; then
+    RETRIEVAL_LEVEL="scars"
+
+# Default: scars (conservative — better to surface something than nothing)
+else
+    RETRIEVAL_LEVEL="scars"
+fi
+
+# ============================================================================
+# Invoke quick-retrieve (Node module)
+# ============================================================================
+
+# Require node for retrieval
+if ! command -v node &>/dev/null; then
+    exit 0
+fi
+
+# Locate quick-retrieve.js relative to plugin root
+# Hook scripts are at: ${CLAUDE_PLUGIN_ROOT}/scripts/
+# Built JS is at:      ${CLAUDE_PLUGIN_ROOT}/../dist/hooks/
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+QUICK_RETRIEVE="${SCRIPT_DIR}/../../dist/hooks/quick-retrieve.js"
+
+# Fallback: try relative to CLAUDE_PLUGIN_ROOT
+if [ ! -f "$QUICK_RETRIEVE" ]; then
+    QUICK_RETRIEVE="${CLAUDE_PLUGIN_ROOT}/../dist/hooks/quick-retrieve.js"
+fi
+
+# If still not found, try the gitmem package location
+if [ ! -f "$QUICK_RETRIEVE" ]; then
+    # Check common install locations
+    for CANDIDATE in \
+        "/workspace/gitmem/dist/hooks/quick-retrieve.js" \
+        "$(npm root -g 2>/dev/null)/gitmem/dist/hooks/quick-retrieve.js" \
+        "$(dirname "$(which gitmem 2>/dev/null)")/../lib/node_modules/gitmem/dist/hooks/quick-retrieve.js"; do
+        if [ -f "$CANDIDATE" ]; then
+            QUICK_RETRIEVE="$CANDIDATE"
+            break
+        fi
+    done
+fi
+
+if [ ! -f "$QUICK_RETRIEVE" ]; then
+    # Can't find quick-retrieve module — fail open
+    exit 0
+fi
+
+# Call quick-retrieve with prompt and level
+# Timeout: 2.5s (leave 500ms buffer within 3s hook timeout)
+RESULT=$(timeout 2.5 node "$QUICK_RETRIEVE" "$PROMPT" "$RETRIEVAL_LEVEL" 2>/dev/null) || true
+
+# Empty result → nothing relevant found
+if [ -z "$RESULT" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# Inject as additionalContext
+# ============================================================================
+
+# Escape the result for JSON embedding
+ESCAPED_RESULT=$(node -e "process.stdout.write(JSON.stringify(process.argv[1]))" "$RESULT" 2>/dev/null) || exit 0
+
+cat <<HOOKJSON
+{
+  "additionalContext": ${ESCAPED_RESULT}
+}
+HOOKJSON
+
+exit 0

package/hooks/scripts/post-tool-use.sh

@@ -0,0 +1,112 @@
+#!/bin/bash
+# GitMem Hooks Plugin — PostToolUse Hook (Audit Trail)
+# Logs LOOKED events (after recall/search) and ACTION events (after consequential actions).
+#
+# Event types:
+#   LOOKED — Agent checked institutional memory (recall, search)
+#   ACTION — Agent took a consequential action (git push, Linear Done, SQL migration)
+#
+# Audit trail: append-only JSONL at /tmp/gitmem-hooks-{SESSION_ID}/audit.jsonl
+# Non-consequential actions pass through silently.
+#
+# Input: JSON via stdin with tool_name, tool_input, tool_output
+# Output: empty (exit 0) — PostToolUse hooks never block
+
+set -e
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat -)
+
+# ============================================================================
+# Graceful degradation: skip if no active gitmem session
+# ============================================================================
+
+# Check active sessions registry (Phase 1 multi-session, GIT-19)
+ACTIVE_SESSIONS=".gitmem/active-sessions.json"
+if [ ! -f "$ACTIVE_SESSIONS" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# JSON parsing helper (jq preferred, node fallback)
+# ============================================================================
+
+parse_json() {
+    local INPUT="$1"
+    local FIELD="$2"
+    if command -v jq &>/dev/null; then
+        echo "$INPUT" | jq -r "$FIELD // empty" 2>/dev/null
+    else
+        echo "$INPUT" | node -e "
+            let d='';
+            process.stdin.on('data',c=>d+=c);
+            process.stdin.on('end',()=>{
+                try {
+                    const j=JSON.parse(d);
+                    const path='$FIELD'.replace(/^\./,'').split('.');
+                    let v=j;
+                    for(const p of path) v=v?.[p];
+                    process.stdout.write(String(v||''));
+                } catch(e) { process.stdout.write(''); }
+            });
+        " 2>/dev/null
+    fi
+}
+
+TOOL_NAME=$(parse_json "$HOOK_INPUT" ".tool_name")
+
+# ============================================================================
+# Classify event: LOOKED or ACTION
+# ============================================================================
+
+EVENT_TYPE=""
+DETAIL=""
+
+case "$TOOL_NAME" in
+    mcp__gitmem__recall|mcp__gitmem__gitmem-r)
+        EVENT_TYPE="LOOKED"
+        PLAN=$(parse_json "$HOOK_INPUT" ".tool_input.plan")
+        DETAIL="plan: ${PLAN:-<no plan>}"
+        ;;
+    mcp__gitmem__search|mcp__gitmem__gm-scar)
+        EVENT_TYPE="LOOKED"
+        QUERY=$(parse_json "$HOOK_INPUT" ".tool_input.query")
+        DETAIL="query: ${QUERY:-<no query>}"
+        ;;
+    Bash)
+        COMMAND=$(parse_json "$HOOK_INPUT" ".tool_input.command")
+        if echo "$COMMAND" | grep -qE '(git\s+push|git\s+tag|npm\s+publish|npx\s+supabase\s+db\s+push|deploy|supabase\s+functions\s+deploy)'; then
+            EVENT_TYPE="ACTION"
+            DETAIL="command: $COMMAND"
+        fi
+        ;;
+    Write|Edit)
+        FILE_PATH=$(parse_json "$HOOK_INPUT" ".tool_input.file_path")
+        if echo "$FILE_PATH" | grep -qE '\.(sql|env)$'; then
+            EVENT_TYPE="ACTION"
+            DETAIL="file: $FILE_PATH"
+        fi
+        ;;
+esac
+
+# Not a tracked event → pass through silently
+if [ -z "$EVENT_TYPE" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# Append to audit trail (JSONL)
+# ============================================================================
+
+SESSION_ID="${CLAUDE_SESSION_ID:-$$}"
+STATE_DIR="/tmp/gitmem-hooks-${SESSION_ID}"
+mkdir -p "$STATE_DIR"
+
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Escape detail for JSON (replace quotes and backslashes)
+DETAIL_ESCAPED=$(echo "$DETAIL" | sed 's/\\/\\\\/g; s/"/\\"/g' | tr '\n' ' ')
+
+echo "{\"timestamp\":\"${TIMESTAMP}\",\"type\":\"${EVENT_TYPE}\",\"tool\":\"${TOOL_NAME}\",\"detail\":\"${DETAIL_ESCAPED}\"}" >> "$STATE_DIR/audit.jsonl"
+
+exit 0

package/hooks/scripts/recall-check.sh

@@ -0,0 +1,213 @@
+#!/bin/bash
+# GitMem Hooks Plugin — PreToolUse Hook (Recall Check + Confirmation Gate)
+#
+# Two enforcement mechanisms for consequential actions:
+#
+# 1. CONFIRMATION GATE (hard block):
+#    If recall() surfaced scars but confirm_scars() hasn't been called → BLOCK.
+#    Uses JSON "decision: block" pattern (same as session-close-check.sh).
+#    Only blocks on recall-source scars; session_start scars don't require confirmation.
+#
+# 2. RECALL NAG (soft reminder):
+#    If recall hasn't been called recently → nudge (additionalContext, never blocks).
+#    - If recall never called AND >3 tool calls → nag
+#    - Cooldown: no more than once per 60 seconds
+#
+# Filter layer: Only triggers on consequential actions:
+#   - Bash: git push, git tag, npm publish, deploy commands
+#   - Write/Edit: .sql migrations, .env files
+#
+# Input: JSON via stdin with tool_name and tool_input
+# Output: JSON with decision:block OR additionalContext OR empty (exit 0)
+
+set -e
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat -)
+
+# ============================================================================
+# Resolve active session from registry (Phase 1 multi-session, GIT-19)
+# ============================================================================
+
+ACTIVE_SESSIONS=".gitmem/active-sessions.json"
+if [ ! -f "$ACTIVE_SESSIONS" ]; then
+    exit 0
+fi
+
+# Get first session ID from registry to find per-session data file
+SESSION_FILE=""
+if command -v jq &>/dev/null; then
+    SID=$(jq -r '.sessions[0].session_id // empty' "$ACTIVE_SESSIONS" 2>/dev/null)
+    [ -n "$SID" ] && SESSION_FILE=".gitmem/sessions/${SID}/session.json"
+elif command -v node &>/dev/null; then
+    SID=$(node -e "const fs=require('fs');try{const r=JSON.parse(fs.readFileSync('$ACTIVE_SESSIONS','utf8'));const s=(r.sessions||[])[0];process.stdout.write(s?.session_id||'')}catch(e){}" 2>/dev/null)
+    [ -n "$SID" ] && SESSION_FILE=".gitmem/sessions/${SID}/session.json"
+fi
+
+if [ -z "$SESSION_FILE" ] || [ ! -f "$SESSION_FILE" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# Extract tool info using jq (node fallback)
+# ============================================================================
+
+parse_json() {
+    local INPUT="$1"
+    local FIELD="$2"
+    if command -v jq &>/dev/null; then
+        echo "$INPUT" | jq -r "$FIELD // empty" 2>/dev/null
+    else
+        echo "$INPUT" | node -e "
+            let d='';
+            process.stdin.on('data',c=>d+=c);
+            process.stdin.on('end',()=>{
+                try {
+                    const j=JSON.parse(d);
+                    const path='$FIELD'.replace(/^\./,'').split('.');
+                    let v=j;
+                    for(const p of path) v=v?.[p];
+                    process.stdout.write(String(v||''));
+                } catch(e) { process.stdout.write(''); }
+            });
+        " 2>/dev/null
+    fi
+}
+
+# Read a numeric field from per-session file safely
+read_session_count() {
+    local JQ_FILTER="$1"
+    local NODE_SCRIPT="$2"
+    if command -v jq &>/dev/null; then
+        jq "$JQ_FILTER" "$SESSION_FILE" 2>/dev/null || echo "0"
+    else
+        node -e "$NODE_SCRIPT" 2>/dev/null || echo "0"
+    fi
+}
+
+TOOL_NAME=$(parse_json "$HOOK_INPUT" ".tool_name")
+
+# ============================================================================
+# Filter layer: Is this a consequential action?
+# ============================================================================
+
+IS_CONSEQUENTIAL=false
+
+case "$TOOL_NAME" in
+    Bash)
+        # Extract the command being run
+        COMMAND=$(parse_json "$HOOK_INPUT" ".tool_input.command")
+        # Check for consequential bash commands
+        if echo "$COMMAND" | grep -qE '(git\s+push|git\s+tag|npm\s+publish|npx\s+supabase\s+db\s+push|deploy|supabase\s+functions\s+deploy)'; then
+            IS_CONSEQUENTIAL=true
+        fi
+        ;;
+    Write|Edit)
+        # Check for sensitive file types
+        FILE_PATH=$(parse_json "$HOOK_INPUT" ".tool_input.file_path")
+        if echo "$FILE_PATH" | grep -qE '\.(sql|env)$'; then
+            IS_CONSEQUENTIAL=true
+        fi
+        ;;
+esac
+
+# Not consequential → pass through silently
+if [ "$IS_CONSEQUENTIAL" != "true" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# CONFIRMATION GATE (runs first — hard block takes priority over soft nag)
+# ============================================================================
+# Block if recall() surfaced scars but confirm_scars() hasn't been called.
+# Only blocks on recall-source scars; session_start scars don't require confirmation.
+
+RECALL_SCAR_COUNT=$(read_session_count \
+    '[.surfaced_scars // [] | .[] | select(.source == "recall")] | length' \
+    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));const c=(s.surfaced_scars||[]).filter(x=>x.source==='recall');process.stdout.write(String(c.length))}catch(e){process.stdout.write('0')}")
+
+CONFIRMATION_COUNT=$(read_session_count \
+    '[.confirmations // [] | .[]] | length' \
+    "const fs=require('fs');try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));process.stdout.write(String((s.confirmations||[]).length))}catch(e){process.stdout.write('0')}")
+
+if [ "$RECALL_SCAR_COUNT" -gt 0 ] 2>/dev/null && [ "$CONFIRMATION_COUNT" -eq 0 ] 2>/dev/null; then
+    # Get scar titles for the error message
+    if command -v jq &>/dev/null; then
+        SCAR_TITLES=$(jq -r '[.surfaced_scars // [] | .[] | select(.source == "recall") | .scar_title] | join(", ")' "$SESSION_FILE" 2>/dev/null || echo "(unknown)")
+    else
+        SCAR_TITLES=$(node -e "
+            const fs=require('fs');
+            try{const s=JSON.parse(fs.readFileSync('$SESSION_FILE','utf8'));
+            const t=(s.surfaced_scars||[]).filter(x=>x.source==='recall').map(x=>x.scar_title);
+            process.stdout.write(t.join(', '))}catch(e){process.stdout.write('(unknown)')}" 2>/dev/null || echo "(unknown)")
+    fi
+
+    cat <<HOOKJSON
+{
+  "decision": "block",
+  "reason": "SCAR CONFIRMATION REQUIRED: recall() surfaced ${RECALL_SCAR_COUNT} scar(s) that have not been confirmed. Call confirm_scars() (or gm-confirm) with APPLYING/N_A/REFUTED for each scar before proceeding.\n\nUnconfirmed scars: ${SCAR_TITLES}\n\nEach scar must be addressed with:\n- APPLYING: past-tense evidence of compliance\n- N_A: explain why the scar doesn't apply\n- REFUTED: acknowledge risk of overriding"
+}
+HOOKJSON
+    exit 0
+fi
+
+# ============================================================================
+# Session state tracking (for nag logic)
+# ============================================================================
+
+SESSION_ID="${CLAUDE_SESSION_ID:-$$}"
+STATE_DIR="/tmp/gitmem-hooks-${SESSION_ID}"
+mkdir -p "$STATE_DIR"
+
+# Increment tool call count
+TOOL_COUNT=0
+if [ -f "$STATE_DIR/tool_call_count" ]; then
+    TOOL_COUNT=$(cat "$STATE_DIR/tool_call_count")
+fi
+TOOL_COUNT=$((TOOL_COUNT + 1))
+echo "$TOOL_COUNT" > "$STATE_DIR/tool_call_count"
+
+# ============================================================================
+# Cooldown check: don't nag more than once per 60 seconds
+# ============================================================================
+
+NOW=$(date +%s)
+LAST_NAG=0
+if [ -f "$STATE_DIR/last_nag_time" ]; then
+    LAST_NAG=$(cat "$STATE_DIR/last_nag_time")
+fi
+
+ELAPSED_SINCE_NAG=$((NOW - LAST_NAG))
+if [ "$ELAPSED_SINCE_NAG" -lt 60 ]; then
+    exit 0
+fi
+
+# ============================================================================
+# RECALL NAG: Nudge if recall hasn't been called
+# ============================================================================
+# Check if any recall-source scars exist. If RECALL_SCAR_COUNT is 0 and
+# we've had >3 tool calls, the agent hasn't called recall at all → nag.
+
+SHOULD_NAG=false
+
+if [ "$RECALL_SCAR_COUNT" -eq 0 ] 2>/dev/null; then
+    # No recall scars found — recall probably wasn't called
+    if [ "$TOOL_COUNT" -gt 3 ]; then
+        SHOULD_NAG=true
+    fi
+fi
+
+# ============================================================================
+# Output nag or pass through
+# ============================================================================
+
+if [ "$SHOULD_NAG" = "true" ]; then
+    echo "$NOW" > "$STATE_DIR/last_nag_time"
+    cat <<'HOOKJSON'
+{
+  "additionalContext": "GITMEM RECALL REMINDER: You're about to take a consequential action but haven't checked institutional memory recently. Consider calling `recall` (or `gitmem-r`) with your plan before proceeding. This surfaces relevant scars that may prevent repeating past mistakes."
+}
+HOOKJSON
+fi
+
+exit 0

package/hooks/scripts/session-close-check.sh

@@ -0,0 +1,116 @@
+#!/bin/bash
+# GitMem Hooks Plugin — Stop Hook (Session Close Check)
+# Ensures session_close is called before the session ends.
+#
+# Logic:
+# 1. Check if session is meaningful (registry has entries, or >5 tool calls, or >5 min)
+# 2. If session was closed properly (registry empty) → allow stop
+# 3. If meaningful but not closed → block with reminder
+# 4. Infinite loop guard: if stop_hook_active flag set → always allow
+# 5. Trivial sessions skip enforcement
+#
+# Input: JSON via stdin (hook event data)
+# Output: JSON with decision: "block" and message if enforcement triggered
+
+set -e
+
+# Read hook input from stdin
+HOOK_INPUT=$(cat -)
+
+# ============================================================================
+# Infinite loop guard
+# ============================================================================
+
+SESSION_ID="${CLAUDE_SESSION_ID:-$$}"
+STATE_DIR="/tmp/gitmem-hooks-${SESSION_ID}"
+
+if [ -f "$STATE_DIR/stop_hook_active" ]; then
+    # Already fired once and blocked — don't block again
+    exit 0
+fi
+
+# ============================================================================
+# Check if session is meaningful
+# ============================================================================
+
+IS_MEANINGFUL=false
+
+ACTIVE_SESSIONS=".gitmem/active-sessions.json"
+SESSION_STARTED=false
+if [ -f "$ACTIVE_SESSIONS" ]; then
+    # Check if registry has active session entries (Phase 1 multi-session, GIT-19)
+    if command -v jq &>/dev/null; then
+        [ "$(jq '.sessions | length' "$ACTIVE_SESSIONS" 2>/dev/null || echo 0)" -gt 0 ] 2>/dev/null && SESSION_STARTED=true
+    elif command -v node &>/dev/null; then
+        [ "$(node -e "const fs=require('fs');try{const r=JSON.parse(fs.readFileSync('$ACTIVE_SESSIONS','utf8'));process.stdout.write(String((r.sessions||[]).length))}catch(e){process.stdout.write('0')}" 2>/dev/null)" -gt 0 ] 2>/dev/null && SESSION_STARTED=true
+    fi
+fi
+
+# Without state dir, we have no tracking data — can't determine meaningfulness.
+# This happens when the SessionStart hook didn't fire (plugin hooks issue).
+# Don't block with bogus defaults — skip enforcement gracefully.
+if [ ! -d "$STATE_DIR" ]; then
+    if [ "$SESSION_STARTED" = "true" ]; then
+        # Session exists but no tracking — create state dir NOW so future
+        # Stop attempts can track from this point forward.
+        mkdir -p "$STATE_DIR"
+        date +%s > "$STATE_DIR/start_time"
+        echo "0" > "$STATE_DIR/tool_call_count"
+    fi
+    # First time seeing this — not meaningful yet
+    exit 0
+fi
+
+# Criterion 1: >5 tool calls
+TOOL_COUNT=0
+if [ -f "$STATE_DIR/tool_call_count" ]; then
+    TOOL_COUNT=$(cat "$STATE_DIR/tool_call_count" 2>/dev/null || echo "0")
+fi
+if [ "$TOOL_COUNT" -gt 5 ]; then
+    IS_MEANINGFUL=true
+fi
+
+# Criterion 2: >5 minutes duration
+NOW=$(date +%s)
+if [ -f "$STATE_DIR/start_time" ]; then
+    START_TIME=$(cat "$STATE_DIR/start_time" 2>/dev/null || echo "$NOW")
+    DURATION=$((NOW - START_TIME))
+    if [ "$DURATION" -gt 300 ]; then
+        IS_MEANINGFUL=true
+    fi
+fi
+
+# ============================================================================
+# Trivial session → skip enforcement
+# ============================================================================
+
+if [ "$IS_MEANINGFUL" != "true" ]; then
+    exit 0
+fi
+
+# ============================================================================
+# Check if session was closed properly
+# ============================================================================
+
+if [ "$SESSION_STARTED" = "true" ]; then
+    # Registry still has entries → session not closed
+    # Set guard flag to prevent infinite blocking
+    mkdir -p "$STATE_DIR"
+    touch "$STATE_DIR/stop_hook_active"
+
+    cat <<'HOOKJSON'
+{
+  "decision": "block",
+  "reason": "GITMEM SESSION STILL OPEN — Run the standard closing ceremony:\n\n1. YOU (the agent) ANSWER these 7 reflection questions based on the session. Display your answers to the human:\n   - what_broke: What broke that you didn't expect?\n   - what_took_longer: What took longer than it should have?\n   - do_differently: What would you do differently next time?\n   - what_worked: What pattern or approach worked well?\n   - wrong_assumption: What assumption was wrong?\n   - scars_applied: Which scars or institutional knowledge did you apply?\n   - institutional_memory: What from this session should be captured?\n\n2. ASK the human: 'Any corrections or additions to my answers?' WAIT for their response.\n\n3. WRITE structured payload to .gitmem/closing-payload.json with closing_reflection (7 fields above, incorporating human corrections), task_completion (timestamps), and human_corrections.\n\n4. CALL session_close with session_id and close_type: 'standard'.\n\nFor trivial sessions (< 30min, exploratory only), use close_type: 'quick' instead — no questions needed."
+}
+HOOKJSON
+    exit 0
+fi
+
+# Session was closed properly (registry empty) or never started
+# Clean up state dir
+if [ -d "$STATE_DIR" ]; then
+    rm -rf "$STATE_DIR"
+fi
+
+exit 0