@paths.design/caws-cli 8.3.0 → 9.0.0

package/dist/scaffold/git-hooks.js

@@ -236,6 +236,128 @@ if [ "$YAML_VALIDATION_FAILED" = true ]; then
   exit 1
 fi
 
+# ===== CAWS Multi-Agent Safety Guard =====
+# Prevents unsafe concurrent operations on shared branches
+
+if [ -d ".caws" ]; then
+  CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+  # Guard 1a: Block commits on base branch when parallel worktrees are active (caws parallel)
+  if [ -f ".caws/parallel.json" ] && command -v node >/dev/null 2>&1; then
+    PARALLEL_BASE=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/parallel.json', 'utf8'));
+        console.log(reg.baseBranch || '');
+      } catch(e) { console.log(''); }
+    " 2>/dev/null)
+
+    if [ -n "$PARALLEL_BASE" ] && [ "$CURRENT_BRANCH" = "$PARALLEL_BASE" ]; then
+      AGENT_COUNT=$(node -e "
+        try {
+          var reg = JSON.parse(require('fs').readFileSync('.caws/parallel.json', 'utf8'));
+          console.log((reg.agents || []).length);
+        } catch(e) { console.log('0'); }
+      " 2>/dev/null)
+
+      if [ "$AGENT_COUNT" -gt 0 ] 2>/dev/null; then
+        echo "BLOCKED: Committing to '$CURRENT_BRANCH' while $AGENT_COUNT parallel agent worktree(s) are active."
+        echo "  Active agents are working in isolated worktrees."
+        echo "  Committing to the base branch risks interleaved history and merge conflicts."
+        echo ""
+        echo "  To see parallel status: caws parallel status"
+        echo "  To merge agent work:    caws parallel merge"
+        echo "  To override (unsafe):   git commit --no-verify"
+        exit 1
+      fi
+    fi
+  fi
+
+  # Guard 1b: Block commits on base branch when ANY active worktrees exist (caws worktree create)
+  if [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+    ACTIVE_WORKTREES=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
+        var wts = Object.values(reg.worktrees || {});
+        var active = wts.filter(function(w) {
+          return w.status === 'active' && w.baseBranch === '$CURRENT_BRANCH';
+        });
+        console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(','));
+      } catch(e) { console.log('0:'); }
+    " 2>/dev/null)
+
+    WT_COUNT=$(echo "$ACTIVE_WORKTREES" | cut -d: -f1)
+    WT_NAMES=$(echo "$ACTIVE_WORKTREES" | cut -d: -f2)
+
+    if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+      echo "BLOCKED: Committing to '$CURRENT_BRANCH' while $WT_COUNT active worktree(s) exist: $WT_NAMES"
+      echo "  You should be working in your worktree, not on the base branch."
+      echo "  Committing here risks interleaved history with agents in worktrees."
+      echo ""
+      echo "  To work in your worktree: cd .caws/worktrees/<name>/"
+      echo "  To see worktrees:         caws worktree list"
+      echo "  To override (unsafe):     git commit --no-verify"
+      exit 1
+    fi
+  fi
+
+  # Guard 2: Warn if multiple active sessions exist on same branch
+  if [ -f ".caws/sessions.json" ] && command -v node >/dev/null 2>&1; then
+    ACTIVE_ON_BRANCH=$(node -e "
+      try {
+        var reg = JSON.parse(require('fs').readFileSync('.caws/sessions.json', 'utf8'));
+        var count = Object.values(reg.sessions || {}).filter(
+          function(s) { return s.status === 'active' && s.branch === '$CURRENT_BRANCH'; }
+        ).length;
+        console.log(count);
+      } catch(e) { console.log('0'); }
+    " 2>/dev/null)
+
+    if [ "$ACTIVE_ON_BRANCH" -gt 1 ] 2>/dev/null; then
+      echo "WARNING: $ACTIVE_ON_BRANCH active sessions detected on branch '$CURRENT_BRANCH'."
+      echo "  Multiple agents committing to the same branch risks interleaved history."
+      echo "  Consider using worktrees: caws parallel setup <plan-file>"
+      echo ""
+    fi
+  fi
+
+  # Guard 3: Block --amend when HEAD commit may not belong to current session
+  # Detect --amend by inspecting the parent git process arguments
+  AMEND_FLAG=false
+  if command -v ps >/dev/null 2>&1; then
+    PARENT_ARGS=$(ps -o args= -p $PPID 2>/dev/null || echo "")
+    case "$PARENT_ARGS" in
+      *--amend*) AMEND_FLAG=true ;;
+    esac
+  fi
+
+  if [ "$AMEND_FLAG" = true ]; then
+    BLOCK_AMEND=false
+    if [ -f ".caws/parallel.json" ]; then
+      BLOCK_AMEND=true
+    elif [ -f ".caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+      HAS_ACTIVE_WT=$(node -e "
+        try {
+          var reg = JSON.parse(require('fs').readFileSync('.caws/worktrees.json', 'utf8'));
+          var active = Object.values(reg.worktrees || {}).filter(function(w) { return w.status === 'active'; });
+          console.log(active.length > 0 ? 'yes' : 'no');
+        } catch(e) { console.log('no'); }
+      " 2>/dev/null)
+      if [ "$HAS_ACTIVE_WT" = "yes" ]; then
+        BLOCK_AMEND=true
+      fi
+    fi
+
+    if [ "$BLOCK_AMEND" = true ]; then
+      echo "BLOCKED: --amend is not allowed while worktrees are active."
+      echo "  Amending commits risks rewriting another agent's work."
+      echo "  Create a new commit instead."
+      echo "  To override (dangerous): git commit --amend --no-verify"
+      exit 1
+    fi
+  fi
+fi
+# ===== End Multi-Agent Safety Guard =====
+
 # Fallback chain for quality gates:
 # 1. Try Node.js script (if exists)
 # 2. Try CAWS CLI
@@ -665,37 +787,89 @@ echo "All quality gates passed - ready to push"
 function generateCommitMsgHook() {
   return `#!/bin/bash
 # CAWS Commit Message Hook
-# Validates commit message format
+# Validates commit message format and enforces merge(worktree): convention
 
 COMMIT_MSG_FILE=$1
 
 # Read the commit message
 COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
 
+# Resolve CAWS root (works from worktrees too)
+CAWS_ROOT="."
+if command -v git >/dev/null 2>&1; then
+  _GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null || echo ".git")
+  if [ "$_GIT_COMMON" != ".git" ]; then
+    _CANDIDATE=$(cd "$_GIT_COMMON/.." 2>/dev/null && pwd || echo "")
+    if [ -n "$_CANDIDATE" ] && [ -d "$_CANDIDATE/.caws" ]; then
+      CAWS_ROOT="$_CANDIDATE"
+    fi
+  fi
+fi
+
 # Check if CAWS is initialized
-if [ ! -d ".caws" ]; then
+if [ ! -d "$CAWS_ROOT/.caws" ]; then
   exit 0
 fi
 
+# ===== Worktree merge message guard =====
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo ".git")
+HAS_ACTIVE_WORKTREES=false
+
+if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  WT_COUNT=$(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' && w.baseBranch === '$CURRENT_BRANCH';
+      });
+      console.log(active.length);
+    } catch(e) { console.log('0'); }
+  " 2>/dev/null)
+  if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+    HAS_ACTIVE_WORKTREES=true
+  fi
+fi
+
+if [ "$HAS_ACTIVE_WORKTREES" = true ]; then
+  IS_GIT_MERGE=false
+  if [ -f "$GIT_DIR/MERGE_HEAD" ]; then
+    IS_GIT_MERGE=true
+  fi
+
+  if [[ "$COMMIT_MSG" =~ ^merge\\(worktree\\): ]] || [ "$IS_GIT_MERGE" = true ]; then
+    echo "Merge commit to base branch allowed (worktrees active)"
+  elif [[ "$COMMIT_MSG" =~ ^wip\\(checkpoint\\): ]]; then
+    echo "Checkpoint commit allowed (prior-session cleanup)"
+  else
+    echo "BLOCKED: Direct commit to '$CURRENT_BRANCH' while worktrees are active."
+    echo "  Only these commit types are allowed on the base branch during parallel work:"
+    echo ""
+    echo "  merge(worktree): <description>     — merge a completed worktree branch"
+    echo "  wip(checkpoint): <description>     — commit prior-session dirty files"
+    echo "  git merge --no-ff <branch>         — git merge commit"
+    echo ""
+    echo "  To override (unsafe):   git commit --no-verify"
+    exit 1
+  fi
+fi
+# ===== End worktree merge message guard =====
+
 # Basic commit message validation
 if [ \${#COMMIT_MSG} -lt 10 ]; then
-  echo "Commit message too short \\(minimum 10 characters\\)"
-  echo "Write descriptive commit messages"
+  echo "Commit message too short (minimum 10 characters)"
+  echo "  Write descriptive commit messages"
   exit 1
 fi
 
 # Check for conventional commit format (optional but encouraged)
-if [[ $COMMIT_MSG =~ ^(feat|fix|docs|style|refactor|test|chore)(.+)? ]]; then
-  echo "Conventional commit format detected"
+if [[ $COMMIT_MSG =~ ^(feat|fix|docs|style|refactor|test|chore|merge|perf|wip)(\\(.*\\))?: ]]; then
+  : # valid format
 else
-  echo "Consider using conventional commit format:"
-  echo "   feat: add new feature"
-  echo "   fix: bug fix"
-  echo "   docs: documentation"
-  echo "   style: formatting"
-  echo "   refactor: code restructuring"
-  echo "   test: testing"
-  echo "   chore: maintenance"
+  if [[ ! $COMMIT_MSG =~ ^Merge\\ (branch|remote) ]]; then
+    echo "Consider using conventional commit format:"
+    echo "   feat: / fix: / docs: / refactor: / chore: / merge(worktree):"
+  fi
 fi
 
 echo "Commit message validation passed"

package/dist/session/session-manager.js

@@ -533,6 +533,19 @@ function findActiveSession(registry) {
   return active.length > 0 ? active[0][0] : null;
 }
 
+/**
+ * Find all active sessions on a specific branch
+ * @param {string} branch - Branch name to search
+ * @returns {Object[]} Active sessions on that branch with id and metadata
+ */
+function findActiveSessionsOnBranch(branch) {
+  const root = getRepoRoot();
+  const registry = loadRegistry(root);
+  return Object.entries(registry.sessions)
+    .filter(([, meta]) => meta.status === 'active' && meta.branch === branch)
+    .map(([id, meta]) => ({ id, ...meta }));
+}
+
 module.exports = {
   startSession,
   checkpointSession,
@@ -545,4 +558,5 @@ module.exports = {
   SESSIONS_DIR,
   REGISTRY_FILE,
   CAPSULE_SCHEMA_VERSION,
+  findActiveSessionsOnBranch,
 };

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

@@ -1,6 +1,7 @@
 #!/bin/bash
 # CAWS Scope Guard Hook for Claude Code
-# Validates file edits against the working spec's scope boundaries
+# Validates file edits against scope boundaries from working-spec + feature specs
+# Specs with terminal status (completed, closed, archived) are skipped
 # @author @darianrosebrook
 
 set -euo pipefail
@@ -25,8 +26,8 @@ PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
 SPEC_FILE="$PROJECT_DIR/.caws/working-spec.yaml"
 SCOPE_FILE="$PROJECT_DIR/.caws/scope.json"
 
-# Check if spec file or scope.json exists
-if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]]; then
+# Check if any spec infrastructure exists
+if [[ ! -f "$SPEC_FILE" ]] && [[ ! -f "$SCOPE_FILE" ]] && [[ ! -d "$PROJECT_DIR/.caws/specs" ]]; then
   exit 0
 fi
 
@@ -119,7 +120,9 @@ if [[ ! -f "$SPEC_FILE" ]] && [[ -f "$SCOPE_FILE" ]]; then
   fi
 fi
 
-# Use Node.js to parse YAML and check scope
+# Use Node.js to parse YAML and check scope across working spec + active feature specs
+SPECS_DIR="$PROJECT_DIR/.caws/specs"
+
 if command -v node >/dev/null 2>&1; then
   SCOPE_CHECK=$(node -e "
     const yaml = require('js-yaml');
@@ -127,26 +130,67 @@ if command -v node >/dev/null 2>&1; then
     const path = require('path');
 
     try {
-      const spec = yaml.load(fs.readFileSync('$SPEC_FILE', 'utf8'));
       const filePath = '$REL_PATH';
 
-      // Check if file is explicitly out of scope
-      const outOfScope = spec.scope?.out || [];
-      for (const pattern of outOfScope) {
-        // Simple glob-like matching
-        const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
-        if (regex.test(filePath)) {
-          console.log('out_of_scope:' + pattern);
-          process.exit(0);
+      // Terminal statuses: specs that are done — scope no longer enforced
+      const TERMINAL = new Set(['completed', 'closed', 'archived']);
+
+      // Smart allowlist: root-level files, .caws/, .claude/ always pass
+      if (!filePath.includes('/') || filePath.startsWith('.caws/') || filePath.startsWith('.claude/')) {
+        console.log('in_scope');
+        process.exit(0);
+      }
+
+      // Collect all active specs (working-spec + feature specs)
+      const specs = [];
+
+      // 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 (_) {}
+      }
+
+      // 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'))) {
+          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 (_) {}
         }
       }
 
-      // Check if file is in scope (if scope is explicitly defined)
-      const inScope = spec.scope?.in || [];
-      if (inScope.length > 0) {
+      // No active specs — allow everything
+      if (specs.length === 0) {
+        console.log('in_scope');
+        process.exit(0);
+      }
+
+      // Check scope.out across ALL active specs — any match blocks
+      for (const { source, spec } of specs) {
+        for (const pattern of (spec.scope?.out || [])) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
+          if (regex.test(filePath)) {
+            console.log('out_of_scope:' + source + ':' + pattern);
+            process.exit(0);
+          }
+        }
+      }
+
+      // Union all scope.in patterns — file must match at least one
+      const allInScope = specs.flatMap(({ spec }) => spec.scope?.in || []);
+      if (allInScope.length > 0) {
         let found = false;
-        for (const pattern of inScope) {
-          const regex = new RegExp(pattern.replace(/\*/g, '.*').replace(/\?/g, '.'));
+        for (const pattern of allInScope) {
+          const regex = new RegExp(pattern.replace(/\\*/g, '.*').replace(/\\?/g, '.'));
           if (regex.test(filePath)) {
             found = true;
             break;
@@ -165,12 +209,14 @@ if command -v node >/dev/null 2>&1; then
   " 2>&1)
 
   if [[ "$SCOPE_CHECK" == out_of_scope:* ]]; then
-    PATTERN="${SCOPE_CHECK#out_of_scope:}"
+    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 the working spec (pattern: '"$PATTERN"'). Editing it may cause scope creep. Please confirm this edit is intentional."
+        "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
@@ -181,7 +227,7 @@ if command -v node >/dev/null 2>&1; then
       "hookSpecificOutput": {
         "hookEventName": "PreToolUse",
         "permissionDecision": "ask",
-        "permissionDecisionReason": "This file ('"$REL_PATH"') is not in the defined scope of the working spec. Editing it may cause scope creep. Please confirm this edit is intentional."
+        "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

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

@@ -0,0 +1,117 @@
+#!/bin/bash
+# CAWS Session Status Hook for Claude Code
+# Reports project state at session start with worktree warnings
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read stdin (required by hook protocol)
+INPUT=$(cat)
+
+# Only run for session-start events
+EVENT_TYPE="${1:-}"
+if [ "$EVENT_TYPE" != "session-start" ]; then
+  exit 0
+fi
+
+# Check if this is a CAWS project
+if [ ! -d "${CLAUDE_PROJECT_DIR:-.}/.caws" ]; then
+  exit 0
+fi
+
+cd "${CLAUDE_PROJECT_DIR:-.}"
+
+# --- Resolve main repo root ---
+CAWS_ROOT="."
+if command -v git >/dev/null 2>&1; then
+  _GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null || echo ".git")
+  if [ "$_GIT_COMMON" != ".git" ]; then
+    _CANDIDATE=$(cd "$_GIT_COMMON/.." 2>/dev/null && pwd || echo "")
+    if [ -n "$_CANDIDATE" ] && [ -d "$_CANDIDATE/.caws" ]; then
+      CAWS_ROOT="$_CANDIDATE"
+    fi
+  fi
+fi
+
+# --- Active worktree warning ---
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1; then
+  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'; });
+      if (active.length > 0) {
+        var names = active.map(function(w) { return w.name + ' (' + w.branch + ')'; });
+        console.log(active.length + ':' + names.join(', '));
+      } else {
+        console.log('0:');
+      }
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  WT_COUNT=$(echo "$WT_INFO" | cut -d: -f1)
+  WT_NAMES=$(echo "$WT_INFO" | cut -d: -f2)
+
+  if [ "$WT_COUNT" -gt 0 ] 2>/dev/null; then
+    # Check if the agent is already in a worktree (not on the base branch)
+    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'; });
+        if (active.length > 0) console.log(active[0].baseBranch || '');
+        else console.log('');
+      } catch(e) { console.log(''); }
+    " 2>/dev/null || echo "")
+
+    echo ""
+    echo "================================================================"
+    echo "  ACTIVE WORKTREES DETECTED: $WT_COUNT worktree(s)"
+    echo "  $WT_NAMES"
+    echo "================================================================"
+
+    if [ -n "$BASE_BRANCH" ] && [ "$CURRENT_BRANCH" = "$BASE_BRANCH" ]; then
+      echo ""
+      echo "  You MUST work in a worktree, not on $CURRENT_BRANCH."
+      echo ""
+      echo "  If a worktree was created for your task:"
+      echo "    cd $CAWS_ROOT/.caws/worktrees/<name>/"
+      echo ""
+      echo "  If you need a new worktree:"
+      echo "    caws worktree create <name>"
+      echo ""
+      echo "  The only operations allowed on $CURRENT_BRANCH are:"
+      echo "    - git merge --no-ff <branch> (merge completed worktree work)"
+      echo "    - Commits with message: merge(worktree): <description>"
+      echo "    - Commits with message: wip(checkpoint): <description>"
+      echo "      (for committing prior-session dirty files)"
+      echo ""
+      echo "  Writing or editing files on $CURRENT_BRANCH will be BLOCKED"
+      echo "  by the PreToolUse hook while worktrees are active."
+    else
+      echo ""
+      echo "  You are on branch '$CURRENT_BRANCH' (worktree). Good."
+      echo "  Other active worktrees: $WT_NAMES"
+    fi
+    echo "================================================================"
+    echo ""
+  fi
+fi
+
+# Use caws session briefing for structured output
+if command -v caws &>/dev/null; then
+  caws session briefing 2>/dev/null || {
+    echo "--- CAWS Session Briefing (fallback) ---"
+    HEAD_SHA=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
+    DIRTY_COUNT=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    echo "Git: ${BRANCH} @ ${HEAD_SHA} (${DIRTY_COUNT} dirty files)"
+    if [ "$DIRTY_COUNT" -gt 0 ]; then
+      echo "WARNING: Working tree has uncommitted changes from a prior session."
+      echo "Classify and commit or stash them before starting new work."
+    fi
+    echo "--- End CAWS Briefing ---"
+  }
+fi
+
+exit 0

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

@@ -0,0 +1,46 @@
+#!/bin/bash
+# CAWS Worktree Cleanup Reminder for Claude Code
+# Warns at session end if active worktrees remain
+# @author @darianrosebrook
+
+set -euo pipefail
+
+# Read JSON input from Claude Code (required by hook protocol)
+INPUT=$(cat)
+
+# Resolve main repo root
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+if command -v git >/dev/null 2>&1; then
+  GIT_COMMON_DIR=$(cd "$PROJECT_DIR" && git rev-parse --git-common-dir 2>/dev/null || echo "")
+  if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != ".git" ]]; then
+    CANDIDATE=$(cd "$PROJECT_DIR" && cd "$GIT_COMMON_DIR/.." 2>/dev/null && pwd || echo "")
+    if [[ -n "$CANDIDATE" ]] && [[ -d "$CANDIDATE/.caws" ]]; then
+      PROJECT_DIR="$CANDIDATE"
+    fi
+  fi
+fi
+
+# Check for active worktrees
+if [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  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'; });
+      if (active.length > 0) {
+        console.log(active.length + ':' + active.map(function(w) { return w.name; }).join(', '));
+      } else {
+        console.log('0:');
+      }
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  COUNT=$(echo "$ACTIVE_INFO" | cut -d: -f1)
+  NAMES=$(echo "$ACTIVE_INFO" | cut -d: -f2)
+
+  if [[ "$COUNT" -gt 0 ]] 2>/dev/null; then
+    echo "REMINDER: $COUNT active worktree(s) remain: $NAMES. Other agents cannot commit to the base branch until all worktrees are destroyed. If your work is complete, run: caws worktree destroy <name> --delete-branch" >&2
+    exit 0
+  fi
+fi
+
+exit 0