@paths.design/caws-cli 9.3.2 → 10.1.0

package/dist/templates/.claude/hooks/doc-frontmatter-check.sh

@@ -0,0 +1,173 @@
+#!/bin/bash
+# Document Frontmatter Check Hook for Claude Code
+# Warns when docs/**/*.md files are written/edited without proper frontmatter.
+# Advisory only — does not block.
+#
+# Validates YAML frontmatter with required fields, authority/status enums,
+# governs requirements for high-authority docs, and verified_at_commit for
+# implementation-state claims.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only check Write and Edit tools
+if [[ "$TOOL_NAME" != "Write" ]] && [[ "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Only check .md files under docs/
+if [[ ! "$FILE_PATH" =~ docs/.*\.md$ ]]; then
+  exit 0
+fi
+
+# Skip exempt filenames
+BASENAME=$(basename "$FILE_PATH")
+if [[ "$BASENAME" == "README.md" ]] || [[ "$BASENAME" == "INDEX.md" ]] || [[ "$BASENAME" == "index.md" ]] || [[ "$BASENAME" == "00_INDEX.md" ]]; then
+  exit 0
+fi
+
+# Skip archive and templates directories
+if [[ "$FILE_PATH" =~ docs/archive/ ]] || [[ "$FILE_PATH" =~ docs/templates/ ]]; then
+  exit 0
+fi
+
+# Skip ephemeral (gitignored, not governed)
+if [[ "$FILE_PATH" =~ docs/ephemeral/ ]]; then
+  exit 0
+fi
+
+# Check if file exists (Write creates it, Edit modifies it)
+if [[ ! -f "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# --- Frontmatter validation ---
+
+# V1: Check for frontmatter delimiters
+FIRST_LINE=$(head -1 "$FILE_PATH" 2>/dev/null || echo "")
+if [[ "$FIRST_LINE" != "---" ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Doc governance (V1): '"$FILE_PATH"' is missing YAML frontmatter. All docs under docs/ (except README.md, archive/, templates/) must start with --- delimiters containing doc_id, authority, status, title, owner, and updated fields."
+    }
+  }'
+  exit 0
+fi
+
+# Extract frontmatter block (between first and second ---)
+FRONTMATTER=$(awk 'NR==1 && /^---$/{found=1; next} found && /^---$/{exit} found{print}' "$FILE_PATH")
+
+if [[ -z "$FRONTMATTER" ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Doc governance (V1): '"$FILE_PATH"' has opening --- but no closing --- for frontmatter block."
+    }
+  }'
+  exit 0
+fi
+
+# V2: Check required fields
+MISSING=""
+for field in doc_id authority status title owner updated; do
+  if ! echo "$FRONTMATTER" | grep -q "^${field}:"; then
+    MISSING="${MISSING} ${field}"
+  fi
+done
+
+if [[ -n "$MISSING" ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Doc governance (V2): '"$FILE_PATH"' is missing required frontmatter fields:'"$MISSING"'."
+    }
+  }'
+  exit 0
+fi
+
+# V2: Check authority value
+AUTHORITY=$(echo "$FRONTMATTER" | grep "^authority:" | head -1 | sed 's/^authority: *//' | tr -d '"' | tr -d "'")
+case "$AUTHORITY" in
+  canonical|policy|architecture|adr|spec|roadmap|reference|working|ephemeral)
+    ;;
+  *)
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Doc governance (V2): '"$FILE_PATH"' has invalid authority '"'"''"$AUTHORITY"''"'"'. Must be one of: canonical, policy, architecture, adr, spec, roadmap, reference, working, ephemeral."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+# V2: Check status value
+STATUS=$(echo "$FRONTMATTER" | grep "^status:" | head -1 | sed 's/^status: *//' | tr -d '"' | tr -d "'")
+case "$STATUS" in
+  draft|active|implemented|proven|superseded|archived)
+    ;;
+  *)
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Doc governance (V2): '"$FILE_PATH"' has invalid status '"'"''"$STATUS"''"'"'. Must be one of: draft, active, implemented, proven, superseded, archived."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+# V3: Check governs for high-authority docs
+case "$AUTHORITY" in
+  canonical|architecture|adr|spec)
+    if ! echo "$FRONTMATTER" | grep -q "^governs:"; then
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PostToolUse",
+          "additionalContext": "Doc governance (V3): '"$FILE_PATH"' has authority '"'"''"$AUTHORITY"''"'"' but no governs section. Docs with authority canonical/architecture/adr/spec must declare what they govern (modules, schemas, or specs)."
+        }
+      }'
+      exit 0
+    fi
+    ;;
+esac
+
+# V4: Check verified_at_commit for implementation-state claims
+case "$STATUS" in
+  implemented|proven)
+    if ! echo "$FRONTMATTER" | grep -q "^verified_at_commit:"; then
+      echo '{
+        "hookSpecificOutput": {
+          "hookEventName": "PostToolUse",
+          "additionalContext": "Doc governance (V4): '"$FILE_PATH"' has status '"'"''"$STATUS"''"'"' but no verified_at_commit. Docs claiming implementation state must declare the commit SHA where claims were verified."
+        }
+      }'
+      exit 0
+    fi
+    ;;
+esac
+
+# V5: Check superseded_by for superseded docs
+if [[ "$STATUS" == "superseded" ]]; then
+  if ! echo "$FRONTMATTER" | grep -q "^superseded_by:"; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Doc governance (V5): '"$FILE_PATH"' has status '"'"'superseded'"'"' but no superseded_by. Superseded docs must declare their replacement doc_id."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+# All checks passed
+exit 0

package/dist/templates/.claude/hooks/protected-paths.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# CAWS Protected Paths Guard for Claude Code
+# Blocks direct Write/Edit access to guard code and guard state.
+# @author @darianrosebrook
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+case "$TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# If you are reading this because a write was blocked, do not edit hook files or
+# strike-state files to bypass a guard. Switch into the correct worktree, fix the
+# active spec scope, or ask the user if the guard itself is wrong.
+case "$FILE_PATH" in
+  */.claude/hooks/*)
+    echo "BLOCKED: $FILE_PATH is protected." >&2
+    echo "Ask the user for permission before editing Claude hook scripts." >&2
+    exit 1
+    ;;
+  */.claude/logs/guard-strikes-*.json)
+    echo "BLOCKED: $FILE_PATH is protected guard state." >&2
+    echo "Do not reset or edit strike counters to bypass enforcement." >&2
+    echo "Switch into the correct worktree, update the active CAWS spec scope, or ask the user for direction instead." >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/dist/templates/.claude/hooks/quality-check.sh

@@ -29,25 +29,39 @@ fi
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 
 # Check if we're in a CAWS project
-if [[ ! -f "$PROJECT_DIR/.caws/working-spec.yaml" ]]; then
+if [[ ! -f "$PROJECT_DIR/.caws/working-spec.yaml" ]] && [[ ! -d "$PROJECT_DIR/.caws/specs" ]]; then
   exit 0
 fi
 
 # Check if CAWS CLI is available
 if ! command -v caws &> /dev/null; then
-  # Suggest installing CAWS
   echo '{
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
-      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @caws/cli"
+      "additionalContext": "CAWS CLI not available. Consider installing with: npm install -g @paths.design/caws-cli"
     }
   }'
   exit 0
 fi
 
-# Run CAWS quality gates in quiet mode for quick feedback
-if caws quality-gates --context=commit --quiet 2>/dev/null; then
-  # Quality check passed - provide positive feedback
+# Run quality gates via the unified pipeline
+RESULT=$(caws gates run --context=edit --file "$FILE_PATH" --json --quiet 2>&1) || GATE_EXIT=$?
+
+if [ -z "$RESULT" ]; then
+  # No output — gates command not available or errored
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Quality gates did not produce output (exit '"${GATE_EXIT:-0}"'). Run '\''caws gates run'\'' for details."
+    }
+  }'
+  exit 0
+fi
+
+# Check if gates passed
+PASSED=$(echo "$RESULT" | jq -r '.passed // true' 2>/dev/null)
+
+if [ "$PASSED" = "true" ]; then
   echo '{
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
@@ -55,13 +69,12 @@ if caws quality-gates --context=commit --quiet 2>/dev/null; then
     }
   }'
 else
-  # Quality check failed - provide feedback to Claude
-  # Run again to get violations summary
-  VIOLATIONS=$(caws quality-gates --context=commit --json 2>/dev/null | jq -r '.violations[:3] | .[] | "- \(.gate): \(.message)"' 2>/dev/null || echo "Run 'caws quality-gates' for details")
+  # Extract top 3 gate failure messages
+  VIOLATIONS=$(echo "$RESULT" | jq -r '[.gates[] | select(.status == "fail") | "- \(.name): \(.messages[0] // "failed")"] | .[0:3] | .[]' 2>/dev/null || echo "Run 'caws gates run' for details")
 
   echo '{
     "decision": "block",
-    "reason": "Quality gate violations detected. Please address the following issues before continuing:\n'"$VIOLATIONS"'\n\nRun '\''caws quality-gates'\'' for full details."
+    "reason": "Quality gate violations detected. Please address the following issues before continuing:\n'"$VIOLATIONS"'\n\nRun '\''caws gates run'\'' for full details."
   }'
 fi
 

package/dist/templates/.claude/hooks/scope-guard.sh

@@ -123,27 +123,28 @@ if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
       }
     " 2>&1)
 
+
+    if [[ "$LITE_CHECK" == error:* ]]; then
+      ERROR_MSG="${LITE_CHECK#error:}"
+      echo "BLOCKED: Scope check failed — cannot verify file is in scope" >&2
+      echo "  Error: $ERROR_MSG" >&2
+      exit 2
+    fi
+
     if [[ "$LITE_CHECK" == banned:* ]]; then
       PATTERN="${LITE_CHECK#banned:}"
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PreToolUse",
-          "permissionDecision": "ask",
-          "permissionDecisionReason": "This file ('"$REL_PATH"') matches a banned pattern ('"$PATTERN"') in .caws/scope.json. Creating files with this pattern is blocked to prevent file sprawl."
-        }
-      }'
-      exit 0
+      echo "BLOCKED: $REL_PATH matches banned pattern ($PATTERN) in .caws/scope.json"
+      echo "  Scope allows: files not matching banned patterns"
+      echo "  To modify scope, update bannedPatterns in .caws/scope.json"
+      exit 2
     fi
 
     if [[ "$LITE_CHECK" == "not_allowed" ]]; then
-      echo '{
-        "hookSpecificOutput": {
-          "hookEventName": "PreToolUse",
-          "permissionDecision": "ask",
-          "permissionDecisionReason": "This file ('"$REL_PATH"') is outside the allowed directories in .caws/scope.json. Please confirm this edit is intentional."
-        }
-      }'
-      exit 0
+      ALLOWED_DIRS=$(node -e "const s=JSON.parse(require('fs').readFileSync('$SCOPE_FILE','utf8')); console.log((s.allowedDirectories||[]).join(', '))" 2>/dev/null || echo "unknown")
+      echo "BLOCKED: $REL_PATH is outside allowed directories"
+      echo "  Scope allows: $ALLOWED_DIRS"
+      echo "  To modify scope, update allowedDirectories in .caws/scope.json"
+      exit 2
     fi
 
     # File is allowed - exit normally
@@ -203,31 +204,83 @@ if command -v node >/dev/null 2>&1; then
         process.exit(0);
       }
 
-      // Collect all active specs (working-spec + feature specs)
-      const specs = [];
+      const projectDir = '$PROJECT_DIR';
 
-      // Load working-spec.yaml if present
-      const mainSpec = '$SPEC_FILE';
-      if (fs.existsSync(mainSpec)) {
-        try {
-          const s = yaml.load(fs.readFileSync(mainSpec, 'utf8'));
-          if (s && !TERMINAL.has(s.status)) {
-            specs.push({ source: 'working-spec', spec: s });
-          }
-        } catch (_) {}
+      // --- Authoritative spec detection ---
+      // If we are inside a worktree with a bound specId, ONLY check that spec.
+      // This prevents unrelated specs from blocking writes via broad scope.out.
+      let authoritativeSpec = null;
+      let mode = 'union';
+
+      const registryPath = path.join(projectDir, '.caws', 'worktrees.json');
+      const cwd = process.cwd();
+      const worktreesBase = path.join(projectDir, '.caws', 'worktrees');
+
+      if (cwd.startsWith(worktreesBase + '/')) {
+        const relative = cwd.slice(worktreesBase.length + 1);
+        const worktreeName = relative.split('/')[0];
+
+        if (worktreeName && fs.existsSync(registryPath)) {
+          try {
+            const reg = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+            const entry = reg.worktrees && reg.worktrees[worktreeName];
+
+            if (entry && entry.specId) {
+              // Try to load the bound spec
+              const specsDir = '$SPECS_DIR';
+              const specCandidates = [
+                path.join(specsDir, entry.specId + '.yaml'),
+                path.join(specsDir, entry.specId + '.yml'),
+              ];
+              for (const candidate of specCandidates) {
+                if (fs.existsSync(candidate)) {
+                  try {
+                    const s = yaml.load(fs.readFileSync(candidate, 'utf8'));
+                    if (s && !TERMINAL.has(s.status)) {
+                      // Verify mutual binding: spec must also reference this worktree
+                      if (s.worktree === worktreeName) {
+                        authoritativeSpec = { source: path.basename(candidate), spec: s };
+                        mode = 'authoritative';
+                      }
+                    }
+                  } catch (_) {}
+                  break;
+                }
+              }
+            }
+          } catch (_) {}
+        }
       }
 
-      // Load feature specs from .caws/specs/
-      const specsDir = '$SPECS_DIR';
-      if (fs.existsSync(specsDir)) {
-        for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+      // --- Collect specs based on mode ---
+      const specs = [];
+
+      if (authoritativeSpec) {
+        // Authoritative: only the bound spec matters
+        specs.push(authoritativeSpec);
+      } else {
+        // Union: load all active specs
+        const mainSpec = '$SPEC_FILE';
+        if (fs.existsSync(mainSpec)) {
           try {
-            const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
+            const s = yaml.load(fs.readFileSync(mainSpec, 'utf8'));
             if (s && !TERMINAL.has(s.status)) {
-              specs.push({ source: f, spec: s });
+              specs.push({ source: 'working-spec', spec: s });
             }
           } catch (_) {}
         }
+
+        const specsDir = '$SPECS_DIR';
+        if (fs.existsSync(specsDir)) {
+          for (const f of fs.readdirSync(specsDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))) {
+            try {
+              const s = yaml.load(fs.readFileSync(path.join(specsDir, f), 'utf8'));
+              if (s && !TERMINAL.has(s.status)) {
+                specs.push({ source: f, spec: s });
+              }
+            } catch (_) {}
+          }
+        }
       }
 
       // No active specs — allow everything
@@ -236,18 +289,18 @@ if command -v node >/dev/null 2>&1; then
         process.exit(0);
       }
 
-      // Check scope.out across ALL active specs — any match blocks
+      // Check scope.out — any match blocks
       for (const { source, spec } of specs) {
         for (const pattern of (spec.scope?.out || [])) {
           const regex = globToRegex(pattern);
           if (regex.test(filePath)) {
-            console.log('out_of_scope:' + source + ':' + pattern);
+            console.log('out_of_scope:' + mode + ':' + source + ':' + pattern);
             process.exit(0);
           }
         }
       }
 
-      // Union all scope.in patterns — file must match at least one
+      // scope.in — file must match at least one pattern
       const allInScope = specs.flatMap(({ spec }) => spec.scope?.in || []);
       if (allInScope.length > 0) {
         let found = false;
@@ -259,7 +312,7 @@ if command -v node >/dev/null 2>&1; then
           }
         }
         if (!found) {
-          console.log('not_in_scope');
+          console.log('not_in_scope:' + mode);
           process.exit(0);
         }
       }
@@ -270,29 +323,57 @@ if command -v node >/dev/null 2>&1; then
     }
   " 2>&1)
 
+
+  if [[ "$SCOPE_CHECK" == error:* ]]; then
+    ERROR_MSG="${SCOPE_CHECK#error:}"
+    echo "BLOCKED: Scope check failed — cannot verify file is in scope" >&2
+    echo "  Error: $ERROR_MSG" >&2
+    echo "  Fix the spec file or scope configuration before editing files" >&2
+    exit 2
+  fi
+
   if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
     DETAIL="${SCOPE_CHECK#out_of_scope:}"
-    SOURCE="${DETAIL%%:*}"
-    PATTERN="${DETAIL#*:}"
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "permissionDecision": "ask",
-        "permissionDecisionReason": "This file ('"$REL_PATH"') is marked as out-of-scope in '"$SOURCE"' (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
-      }
-    }'
-    exit 0
+    # Format: mode:source:pattern
+    MODE="${DETAIL%%:*}"
+    REST="${DETAIL#*:}"
+    SOURCE="${REST%%:*}"
+    PATTERN="${REST#*:}"
+    echo "BLOCKED: $REL_PATH is excluded by scope.out in $SOURCE (pattern: $PATTERN)"
+    if [[ "$MODE" == "union" ]]; then
+      echo "  Mode: union (no authoritative spec bound to this worktree)"
+      echo "  The scope guard is checking ALL active specs because the worktree<->spec"
+      echo "  binding is missing. An unrelated spec may be blocking this edit."
+      echo "  Fix: caws worktree bind <your-spec-id>"
+      echo "  Diagnose: caws scope show"
+    else
+      echo "  Mode: authoritative (checking only your bound spec)"
+      echo "  To modify scope, update the spec's scope.out field"
+    fi
+    exit 2
   fi
 
+  if [[ "$SCOPE_CHECK" == not_in_scope:* ]]; then
+    MODE="${SCOPE_CHECK#not_in_scope:}"
+    echo "BLOCKED: $REL_PATH is not in the defined scope.in of any active spec"
+    if [[ "$MODE" == "union" ]]; then
+      echo "  Mode: union (no authoritative spec bound to this worktree)"
+      echo "  The scope guard is checking ALL active specs because the worktree<->spec"
+      echo "  binding is missing. Your file may be in a scope that no spec covers."
+      echo "  Fix: caws worktree bind <your-spec-id>"
+      echo "  Diagnose: caws scope show"
+    else
+      echo "  Mode: authoritative (checking only your bound spec)"
+      echo "  To modify scope, update the spec's scope.in field"
+    fi
+    exit 2
+  fi
+
+  # Legacy fallback for unqualified not_in_scope (shouldn't happen with updated logic)
   if [[ "$SCOPE_CHECK" == "not_in_scope" ]]; then
-    echo '{
-      "hookSpecificOutput": {
-        "hookEventName": "PreToolUse",
-        "permissionDecision": "ask",
-        "permissionDecisionReason": "This file ('"$REL_PATH"') is not in the defined scope of any active spec. Editing it may cause scope creep. Please confirm this edit is intentional."
-      }
-    }'
-    exit 0
+    echo "BLOCKED: $REL_PATH is not in the defined scope.in of any active spec"
+    echo "  Diagnose: caws scope show"
+    exit 2
   fi
 fi
 

package/dist/templates/.claude/hooks/session-caws-status.sh

@@ -40,7 +40,7 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
   WT_INFO=$(node -e "
     try {
       var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
-      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
       if (active.length > 0) {
         var names = active.map(function(w) { return w.name + ' (' + w.branch + ')'; });
         console.log(active.length + ':' + names.join(', '));
@@ -58,7 +58,7 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
     BASE_BRANCH=$(node -e "
       try {
         var reg = JSON.parse(require('fs').readFileSync('$CAWS_ROOT/.caws/worktrees.json', 'utf8'));
-        var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+        var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
         if (active.length > 0) console.log(active[0].baseBranch || '');
         else console.log('');
       } catch(e) { console.log(''); }

package/dist/templates/.claude/hooks/session-log.sh

@@ -548,13 +548,86 @@ handle_pre_compact() {
   generate_session_output "$(resolve_transcript)"
 }
 
+# ============================================================
+# Agent registry heartbeat — register this agent with CAWS
+# ============================================================
+AGENTS_REGISTRY="${CWD}/.caws/agents.json"
+
+heartbeat_agent() {
+  [ "$SESSION_ID" = "unknown" ] && return
+  [ ! -d "${CWD}/.caws" ] && return
+
+  local model_val
+  model_val=$(echo "$INPUT" | jq -r '.model // "unknown"' 2>/dev/null)
+
+  local registry
+  if [ -f "$AGENTS_REGISTRY" ]; then
+    registry=$(cat "$AGENTS_REGISTRY" 2>/dev/null || echo '{"version":1,"agents":{}}')
+  else
+    registry='{"version":1,"agents":{}}'
+  fi
+
+  registry=$(echo "$registry" | python3 -c "
+import json, sys
+from datetime import datetime, timedelta, timezone
+
+TTL = timedelta(minutes=30)
+now = datetime.now(timezone.utc)
+sid = '$SESSION_ID'
+model = '$model_val'
+
+data = json.load(sys.stdin)
+agents = data.get('agents', {})
+
+pruned = {}
+for k, entry in agents.items():
+    try:
+        last = datetime.fromisoformat(entry['lastSeen'].replace('Z', '+00:00'))
+        if now - last < TTL:
+            pruned[k] = entry
+    except (KeyError, ValueError):
+        pass
+
+existing = pruned.get(sid, {})
+pruned[sid] = {
+    'sessionId': sid,
+    'platform': 'claude-code',
+    'model': model if model != 'unknown' else existing.get('model'),
+    'specId': existing.get('specId'),
+    'ttl': 1800000,
+    'firstSeen': existing.get('firstSeen', now.strftime('%Y-%m-%dT%H:%M:%SZ')),
+    'lastSeen': now.strftime('%Y-%m-%dT%H:%M:%SZ'),
+}
+
+data['agents'] = pruned
+json.dump(data, sys.stdout, indent=2)
+" 2>/dev/null)
+
+  [ -n "$registry" ] && echo "$registry" > "$AGENTS_REGISTRY"
+}
+
+remove_agent() {
+  [ "$SESSION_ID" = "unknown" ] && return
+  [ ! -f "$AGENTS_REGISTRY" ] && return
+
+  python3 -c "
+import json
+sid = '$SESSION_ID'
+with open('$AGENTS_REGISTRY', 'r') as f:
+    data = json.load(f)
+data.get('agents', {}).pop(sid, None)
+with open('$AGENTS_REGISTRY', 'w') as f:
+    json.dump(data, f, indent=2)
+" 2>/dev/null || true
+}
+
 # ============================================================
 # DISPATCH
 # ============================================================
 case "$HOOK_EVENT" in
-  SessionStart)   handle_session_start ;;
-  Stop)           handle_stop ;;
-  PreCompact)     handle_pre_compact ;;
+  SessionStart)   handle_session_start; heartbeat_agent ;;
+  Stop)           handle_stop; remove_agent ;;
+  PreCompact)     handle_pre_compact; heartbeat_agent ;;
   *)              ;; # Other events: no-op
 esac
 

package/dist/templates/.claude/hooks/stop-worktree-check.sh

@@ -25,7 +25,7 @@ if [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>
   ACTIVE_INFO=$(node -e "
     try {
       var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
-      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+      var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active' || w.status === 'fresh' || w.status === 'merged'; });
       if (active.length > 0) {
         console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
       } else {