Debounce Stop hooks to prevent duplicate artifacts per turn

Claude Code fires Stop on every assistant turn, not just session end.
Without debouncing, handoff/decision/feedback hooks re-parse the full
transcript and create duplicate artifacts every response. 5-minute
cooldown per hook per session via session_state.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: sgx-labs

internal/hooks/decision_extractor.go

@@ -10,7 +10,11 @@ import (
 )
 
 // runDecisionExtractor reads the transcript, extracts decisions, and appends to the log.
-func runDecisionExtractor(_ *store.DB, input *HookInput) *HookOutput {
+func runDecisionExtractor(db *store.DB, input *HookInput) *HookOutput {
+	if stopHookDebounce(db, input.SessionID, "decision-extractor") {
+		return nil
+	}
+
 	transcriptPath := input.TranscriptPath
 	if transcriptPath == "" {
 		writeVerboseLog("decision-extractor: no transcript path provided\n")

internal/hooks/feedback.go

@@ -14,6 +14,10 @@ import (
 // This closes the learning loop: notes that get used rise in confidence,
 // notes that are surfaced but ignored gradually decay.
 func runFeedbackLoop(db *store.DB, input *HookInput) *HookOutput {
+	if stopHookDebounce(db, input.SessionID, "feedback-loop") {
+		return nil
+	}
+
 	if input.TranscriptPath == "" || input.SessionID == "" {
 		writeVerboseLog("feedback-loop: no transcript path or session ID provided\n")
 		return nil

internal/hooks/handoff_generator.go

@@ -3,13 +3,47 @@ package hooks
 import (
 	"fmt"
 	"os"
+	"strconv"
+	"time"
 
 	"github.com/sgx-labs/statelessagent/internal/memory"
 	"github.com/sgx-labs/statelessagent/internal/store"
 )
 
+// stopHookCooldown is the minimum seconds between successive runs of each
+// Stop hook within the same session. Claude Code fires the Stop event on
+// every assistant turn, not just session end — without debouncing, hooks
+// would re-parse the transcript and create duplicate artifacts every turn.
+const stopHookCooldown = 300 // 5 minutes
+
+// stopHookDebounce checks whether a Stop hook ran recently for this session.
+// Returns true if the hook should be skipped (still within cooldown).
+// On first run or after cooldown expires, returns false and records the timestamp.
+func stopHookDebounce(db *store.DB, sessionID, hookName string) bool {
+	if sessionID == "" {
+		return false // no session tracking possible, let it run
+	}
+	key := "stop_cooldown_" + hookName
+	if last, ok := db.SessionStateGet(sessionID, key); ok {
+		if ts, err := strconv.ParseInt(last, 10, 64); err == nil {
+			if time.Now().Unix()-ts < stopHookCooldown {
+				writeVerboseLog(fmt.Sprintf("%s: skipped (cooldown, last ran %ds ago)\n",
+					hookName, time.Now().Unix()-ts))
+				return true
+			}
+		}
+	}
+	// Record this run
+	_ = db.SessionStateSet(sessionID, key, strconv.FormatInt(time.Now().Unix(), 10))
+	return false
+}
+
 // runHandoffGenerator generates a handoff note from the transcript.
-func runHandoffGenerator(_ *store.DB, input *HookInput) *HookOutput {
+func runHandoffGenerator(db *store.DB, input *HookInput) *HookOutput {
+	if stopHookDebounce(db, input.SessionID, "handoff-generator") {
+		return nil
+	}
+
 	transcriptPath := input.TranscriptPath
 	if transcriptPath == "" {
 		writeVerboseLog("handoff-generator: no transcript path provided\n")