@paths.design/caws-cli 11.1.6 → 11.1.7

package/templates/hook-packs/claude-code/agent-heartbeat.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 5
+# caws_min_major: 11
+# lineage_refs: 19
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# PreToolUse handler — heartbeats the current session's lease and surfaces
+# parallel-agent presence to the calling agent
+# (MULTI-AGENT-ACTIVITY-REGISTRY-001).
+#
+# Sourcing: invoked by dispatch/pre_tool_use.sh (FIRST in the handler
+# list) after parse-input.sh has populated HOOK_SESSION_ID. The dispatcher
+# runs with --short-circuit-on-block; this handler must never block.
+#
+# Behavior:
+#   - Refuses on empty/unknown HOOK_SESSION_ID.
+#   - Invokes `caws agents heartbeat --session-id <id> --platform claude-code
+#     --throttle 30000 --reason pre_tool_use --json --include-active-summary`.
+#   - Parses CAWS-native JSON. When active_agent_count > 1, wraps the
+#     active_agents list into Claude Code's hookSpecificOutput.
+#     additionalContext envelope and emits it on stdout. When the count
+#     is 1 (self only), emits nothing — silent in the common case.
+#   - Throttled invocations still return an active_agents summary, so
+#     parallel-presence surfacing fires every tool call even when the
+#     write was skipped.
+#
+# IO BOUNDARY: this script is the ONLY surface that emits Claude Code's
+# hookSpecificOutput.additionalContext envelope for lease state. The CLI
+# emits CAWS-native JSON only. A Cursor or terminal integration would
+# rewrite this script to emit its own protocol-specific output while
+# reusing the same `caws agents heartbeat --json --include-active-summary`
+# command verbatim.
+#
+# RUNTIME DEPENDENCIES: bash + node. node is already required by the CAWS
+# CLI itself (which is a Node binary), so depending on it here adds no new
+# runtime surface area. We do NOT depend on jq — jq is not guaranteed
+# present on every install target (it is absent from many container base
+# images and minimal CI runners), and a missing jq would silently drop
+# every parallel-agent notice. The product goal is "agents see each
+# other": that visibility cannot depend on a shell utility outside the
+# CAWS toolchain.
+#
+# FAIL-CLOSED-NON-BLOCKING: if the CLI is absent, fails, or returns
+# malformed JSON, this hook exits 0 silently. Heartbeat is observability
+# and parallel-agent surfacing; a failure must never block the tool call.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+if [[ -z "${HOOK_SESSION_ID:-}" || "$HOOK_SESSION_ID" == "unknown" ]]; then
+  exit 0
+fi
+
+CAWS_BIN="${CAWS_BIN:-caws}"
+if ! command -v "$CAWS_BIN" >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Capture both stdout (JSON) and stderr (diagnostics). On any CLI error,
+# fall through to silent exit.
+CLI_OUT="$(
+  "$CAWS_BIN" agents heartbeat \
+    --session-id "$HOOK_SESSION_ID" \
+    --platform claude-code \
+    --throttle 30000 \
+    --reason pre_tool_use \
+    --json \
+    --include-active-summary \
+  2>/dev/null
+)" || exit 0
+
+if [[ -z "$CLI_OUT" ]]; then
+  exit 0
+fi
+
+# Parse the CAWS-native JSON and, when active_agent_count > 1, compose
+# Claude Code's hookSpecificOutput.additionalContext envelope. A single
+# node invocation does the whole pipeline: parse → filter peers → format
+# bullet list → wrap envelope → emit. Malformed input, parse errors, or
+# any thrown exception fall through to silent exit (fail-closed-non-
+# blocking). Node is already a hard CAWS dependency — the CLI binary
+# IS node — so this adds no new runtime surface vs. jq.
+printf '%s' "$CLI_OUT" | node -e '
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => { raw += chunk; });
+  process.stdin.on("end", () => {
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { process.exit(0); }
+    const count = Number(parsed && parsed.active_agent_count);
+    if (!Number.isFinite(count) || count <= 1) process.exit(0);
+    const agents = Array.isArray(parsed.active_agents) ? parsed.active_agents : [];
+    const peers = agents.filter((a) => a && a.is_self !== true);
+    if (peers.length === 0) process.exit(0);
+    const bullets = peers.map((a) => {
+      const worktree = a.bound_worktree || "no worktree";
+      const spec = a.bound_spec_id ? " — spec " + a.bound_spec_id : "";
+      const kind = a.git_dir_kind || "unknown";
+      const branch = a.branch || "-";
+      const ageMs = Number(a.last_active_age_ms);
+      const ageSec = Number.isFinite(ageMs) ? Math.floor(ageMs / 1000) : 0;
+      return "• " + (a.session_id || "<unknown>") +
+        " (" + worktree + ")" + spec +
+        " — git_dir_kind=" + kind +
+        " — branch=" + branch +
+        " — last active " + ageSec + "s ago";
+    }).join("\n");
+    const ctx = "MULTI-AGENT NOTICE: " + count +
+      " agents active in this repo (including this session). Other active sessions:\n" +
+      bullets + "\n\n" +
+      "Coordinate via '\''caws agents list'\'' and '\''caws status'\'' before " +
+      "mutating shared state. Authority remains in .caws/worktrees.json " +
+      "(ownership) and .caws/specs/<id>.yaml (scope) — leases are " +
+      "visibility only.";
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        additionalContext: ctx,
+      },
+    }));
+  });
+' 2>/dev/null || exit 0
+
+exit 0

package/templates/hook-packs/claude-code/agent-register.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 5
+# caws_min_major: 11
+# lineage_refs: 19
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# SessionStart handler — agent self-registration into the .caws/leases/
+# liveness substrate (MULTI-AGENT-ACTIVITY-REGISTRY-001).
+#
+# Sourcing: invoked by dispatch/session_start.sh after parse-input.sh has
+# populated HOOK_SESSION_ID. Reads HOOK_INPUT_JSON from stdin (unused for
+# this handler beyond the parse-input contract).
+#
+# Behavior:
+#   - Refuses to run when HOOK_SESSION_ID is empty or "unknown" (the
+#     parse-input.sh fallback). A lease whose filename is "unknown.json"
+#     would collide across every session that hits the same fallback.
+#   - Invokes `caws agents register --session-id <id> --platform claude-code
+#     --reason session_start` to write the lease through the CLI.
+#   - Non-blocking. Any failure of the CLI surfaces as stderr only;
+#     SessionStart never fails on hook errors.
+#
+# IO boundary: this script is the only place that knows about Claude Code's
+# SessionStart payload. The CLI receives explicit flags and returns
+# CAWS-native JSON. The hook script does not produce additionalContext
+# at SessionStart — the parallel-agent surfacing happens at PreToolUse
+# via agent-heartbeat.sh.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+# Refuse on empty/unknown session id. Writing a lease at "unknown.json"
+# would collide across every session that hits the parse-input fallback.
+if [[ -z "${HOOK_SESSION_ID:-}" || "$HOOK_SESSION_ID" == "unknown" ]]; then
+  exit 0
+fi
+
+# Locate caws binary. Prefer a project-local install (consistent with the
+# repo's installed CLI version); fall back to PATH.
+CAWS_BIN="${CAWS_BIN:-caws}"
+if ! command -v "$CAWS_BIN" >/dev/null 2>&1; then
+  # No CAWS binary on PATH — silent skip. Liveness is best-effort.
+  exit 0
+fi
+
+# Invoke register. Send stderr to a buffer; we may want to attribute it
+# in dispatcher output (prefixed by run-handlers).
+"$CAWS_BIN" agents register \
+  --session-id "$HOOK_SESSION_ID" \
+  --platform claude-code \
+  --reason session_start \
+  >/dev/null 2>&1 || true
+
+# Never block SessionStart.
+exit 0

package/templates/hook-packs/claude-code/agent-stop.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 5
+# caws_min_major: 11
+# lineage_refs: 19
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# Stop handler — marks the current session's lease as stopped on clean
+# session exit (MULTI-AGENT-ACTIVITY-REGISTRY-001).
+#
+# Sourcing: invoked by dispatch/stop.sh after parse-input.sh has populated
+# HOOK_SESSION_ID.
+#
+# Behavior:
+#   - Refuses on empty/unknown HOOK_SESSION_ID.
+#   - Invokes `caws agents stop --session-id <id> --platform claude-code`
+#     which writes a mark_stopped LeasePatch (status: stopped, stopped_at
+#     timestamp). The lease file is preserved as evidence; hard deletion
+#     happens only via explicit `caws agents prune`.
+#   - Non-blocking. Stop semantics already require all handlers to be
+#     best-effort; a Stop failure is a warn, not a block.
+#
+# Note: Stop is NOT a guaranteed signal. A SIGKILL'd or crashed Claude
+# Code session never reaches Stop. The primary liveness mechanism is
+# heartbeat — Stop is the clean-exit optimization that lets observers
+# distinguish "stopped cleanly" from "went stale and is presumed dead."
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh" 2>/dev/null || exit 0
+parse_hook_input || exit 0
+
+if [[ -z "${HOOK_SESSION_ID:-}" || "$HOOK_SESSION_ID" == "unknown" ]]; then
+  exit 0
+fi
+
+CAWS_BIN="${CAWS_BIN:-caws}"
+if ! command -v "$CAWS_BIN" >/dev/null 2>&1; then
+  exit 0
+fi
+
+"$CAWS_BIN" agents stop \
+  --session-id "$HOOK_SESSION_ID" \
+  --platform claude-code \
+  >/dev/null 2>&1 || true
+
+exit 0

package/templates/hook-packs/claude-code/audit.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 9
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/block-dangerous.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 1,17
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/classify_command.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 1,17
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/dispatch/post_tool_use.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/dispatch/pre_tool_use.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
-# lineage_refs: 8,11,17
+# lineage_refs: 8,11,17,19
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 #
 # PreToolUse dispatcher for Claude Code hooks.
@@ -40,7 +40,16 @@ source "$HOOKS_DIR/lib/run-handlers.sh" 2>/dev/null || exit 0
 
 # Registered handlers in execution order. Each handler self-filters
 # on $HOOK_TOOL_NAME; non-matching cases return exit 0 cheaply.
+#
+# MULTI-AGENT-ACTIVITY-REGISTRY-001: agent-heartbeat.sh runs FIRST so the
+# lease is refreshed and parallel-agent presence is surfaced even when a
+# later guard short-circuits the chain with exit 2 (block). Heartbeat is
+# non-blocking and never produces a "block" decision — its stdout is a
+# Claude-Code additionalContext envelope (priority 1), so it does not
+# outrank a real block from scope-guard / worktree-guard. The dispatcher's
+# stdout-priority logic ensures a block from a later handler still wins.
 HANDLERS=(
+  agent-heartbeat.sh
   block-dangerous.sh
   worktree-guard.sh
   scope-guard.sh

package/templates/hook-packs/claude-code/dispatch/session_start.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
-# lineage_refs: 10,11
+# lineage_refs: 10,11,19
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 # SessionStart dispatcher for Claude Code hooks.
 #
@@ -36,6 +36,10 @@ HANDLERS=(
   "audit.sh session-start"
   # "session-caws-status.sh session-start"
   "session-log.sh"
+  # MULTI-AGENT-ACTIVITY-REGISTRY-001: self-register into the leases
+  # substrate so other sessions can see this one. Non-blocking; refuses
+  # silently when HOOK_SESSION_ID is empty or "unknown".
+  "agent-register.sh"
 )
 
 run_handlers "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/dispatch/stop.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
-# lineage_refs: 10
+# lineage_refs: 10,19
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 # Stop dispatcher for Claude Code hooks.
 #
@@ -32,6 +32,11 @@ HANDLERS=(
   # "stop-worktree-check.sh"
   "plan-transcript-finalize.sh"
   "session-log.sh"
+  # MULTI-AGENT-ACTIVITY-REGISTRY-001: mark our lease as stopped so other
+  # sessions can distinguish "stopped cleanly" from "went stale and is
+  # presumed dead." Non-blocking; refuses silently when HOOK_SESSION_ID
+  # is empty or "unknown".
+  "agent-stop.sh"
 )
 
 run_handlers "${HANDLERS[@]}"

package/templates/hook-packs/claude-code/guard-strikes.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/lib/parse-input.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/lib/run-handlers.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/reset-danger-latch.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 17
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/reset-strikes.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 17
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/runtime-paths.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/scope-guard.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 8,11,12,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/session-caws-status.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 4,11
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
@@ -109,6 +109,12 @@ if [ -f "$CAWS_ROOT/.caws/worktrees.json" ] && command -v node >/dev/null 2>&1;
       echo "  Worktree lifecycle commands (create/destroy/merge) return in"
       echo "  CAWS v11.1+; if you are on v11.0 they are not yet available."
       echo ""
+      echo "  CANONICAL-CHECKOUT-WORKTREE-GUARD-001 active:"
+      echo "    Mutating git commands from this checkout (checkout, switch,"
+      echo "    branch -f, reset non-hard) are now BLOCKED while worktrees"
+      echo "    are active. Read-only commands remain allowed. To act on a"
+      echo "    worktree's branch, enter the worktree first."
+      echo ""
     else
       echo ""
       echo "  You are on branch '$CURRENT_BRANCH' (worktree). Good."

package/templates/hook-packs/claude-code/session-log.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 10
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`

package/templates/hook-packs/claude-code/worktree-guard.sh

@@ -1,9 +1,9 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
-# lineage_refs: 4,6,11
+# lineage_refs: 4,6,11,19
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 #
 # CAWS Worktree Safety Guard for Claude Code (v11-shape).
@@ -50,11 +50,137 @@ if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--sc
 fi
 
 if echo "$COMMAND" | grep -qE '(^|;|&&|\|)\s*git\s+sparse-checkout'; then
-  echo "BLOCKED: git sparse-checkout is not allowed in this project." >&2
-  echo "Use full worktrees without sparse-checkout." >&2
+  # WORKTREE-SPEC-CANONICAL-ACCESS-GUARD-001 A3: blanket refusal stays.
+  # Agent-issued git sparse-checkout commands are refused regardless of
+  # subcommand (disable / set / init / reapply / list / add). Recovery
+  # of the canonical-spec-materialization invariant in a linked CAWS
+  # worktree is a CAWS worktree-repair concern routed through the CLI,
+  # not an agent-Bash git operation.
+  echo "BLOCKED: agent-issued git sparse-checkout is refused in CAWS projects." >&2
+  echo "" >&2
+  echo "Sparse-checkout in a CAWS linked worktree carries the mechanical guard" >&2
+  echo "against the v10.2 split-brain authority class: .caws/specs/ is excluded" >&2
+  echo "from the worktree by design, so canonical spec authority cannot be" >&2
+  echo "materialized inside the worktree as a divergent private copy. Disabling" >&2
+  echo "sparse-checkout (or any sparse-checkout reconfiguration via agent Bash)" >&2
+  echo "would re-open that class. Linked worktrees must not use worktree-local" >&2
+  echo ".caws/specs/ files as authority; CAWS resolves spec reads through the" >&2
+  echo "canonical control plane regardless of cwd." >&2
+  echo "" >&2
+  echo "To read a spec from any cwd (including this worktree), use:" >&2
+  echo "  caws specs show <id>" >&2
+  echo "" >&2
+  echo "To check scope from any cwd, use:" >&2
+  echo "  caws scope show <path>" >&2
+  echo "  caws scope check <path>" >&2
+  echo "" >&2
+  echo "To restore the sparse-checkout invariant on a linked worktree (e.g.," >&2
+  echo "after a human-authorized sparse-checkout reconfiguration left the tree" >&2
+  echo "with materialized .caws/specs/ files), run from the canonical checkout:" >&2
+  echo "  caws worktree repair-sparse <name>" >&2
+  echo "" >&2
+  echo "The repair command is non-destructive: it refuses dirty .caws/specs/" >&2
+  echo "rather than stashing, cleaning, or deleting work." >&2
   exit 2
 fi
 
+# ─── CANONICAL-CHECKOUT-WORKTREE-GUARD-001 (Entry 19) ────────────────
+# Block mutating git commands from the canonical checkout while at
+# least one active CAWS worktree exists. Hook-layer enforcement only:
+# authority remains in worktrees.json + specs. The guard's refusal
+# predicate is conjunctive: canonical + worktrees-active + mutating
+# command. Any one false MUST allow.
+#
+# Leases (.caws/leases/*.json) are NOT consulted by this decision —
+# stale-lease-is-evidence-never-authority. The block decision uses
+# worktrees.json's active entries only.
+canonical_guard_emit_block() {
+  local action="$1"
+  local first_active="$2"
+  echo "BLOCKED: $action from the canonical checkout while CAWS worktrees are active." >&2
+  echo "Active worktree(s) detected (e.g. '$first_active' in .caws/worktrees.json)." >&2
+  echo "Switch into your worktree before mutating: cd .caws/worktrees/$first_active" >&2
+  echo "Or destroy any worktree that is genuinely abandoned: caws worktree destroy <name>" >&2
+}
+
+# Determine whether the session's cwd is the canonical checkout.
+# git_dir == git_common_dir indicates canonical; a linked worktree has
+# git_dir under git_common_dir/worktrees/<name>/.
+CANONICAL_GUARD_CHECK_CWD="${HOOK_CWD:-$PROJECT_DIR}"
+if command -v git >/dev/null 2>&1 && [[ -d "$CANONICAL_GUARD_CHECK_CWD" ]]; then
+  GIT_DIR_RESOLVED=$(cd "$CANONICAL_GUARD_CHECK_CWD" && git rev-parse --git-dir 2>/dev/null | head -1 || echo "")
+  GIT_COMMON_RESOLVED=$(cd "$CANONICAL_GUARD_CHECK_CWD" && git rev-parse --git-common-dir 2>/dev/null | head -1 || echo "")
+  if [[ -n "$GIT_DIR_RESOLVED" ]] && [[ -n "$GIT_COMMON_RESOLVED" ]]; then
+    # Normalize to absolute paths so equality is structural, not textual.
+    GIT_DIR_ABS=$(cd "$CANONICAL_GUARD_CHECK_CWD" && cd "$GIT_DIR_RESOLVED" 2>/dev/null && pwd || echo "$GIT_DIR_RESOLVED")
+    GIT_COMMON_ABS=$(cd "$CANONICAL_GUARD_CHECK_CWD" && cd "$GIT_COMMON_RESOLVED" 2>/dev/null && pwd || echo "$GIT_COMMON_RESOLVED")
+    if [[ "$GIT_DIR_ABS" == "$GIT_COMMON_ABS" ]]; then
+      # We are in the canonical checkout. Now check for active worktrees.
+      WORKTREES_JSON="$PROJECT_DIR/.caws/worktrees.json"
+      if [[ -f "$WORKTREES_JSON" ]] && command -v node >/dev/null 2>&1; then
+        FIRST_ACTIVE_WT=$(node -e "
+          try {
+            var reg = JSON.parse(require('fs').readFileSync('$WORKTREES_JSON', 'utf8'));
+            function entriesOf(r) {
+              if (!r || typeof r !== 'object') return [];
+              if (r.worktrees && typeof r.worktrees === 'object') {
+                return Object.entries(r.worktrees);
+              }
+              var out = [];
+              for (var k in r) {
+                if (Object.prototype.hasOwnProperty.call(r, k)) {
+                  var v = r[k];
+                  if (v && typeof v === 'object') out.push([k, v]);
+                }
+              }
+              return out;
+            }
+            var entries = entriesOf(reg);
+            // 'active' is the documented status; entries without an
+            // explicit status (legacy/in-flight registry shapes) are
+            // also treated as active because the CLI's createWorktree
+            // does not always emit a status field.
+            var active = entries.filter(function(e) {
+              var s = e[1] && e[1].status;
+              return s === 'active' || s === undefined || s === null || s === '';
+            });
+            if (active.length > 0) console.log(active[0][0]);
+            else console.log('');
+          } catch(e) { console.log(''); }
+        " 2>/dev/null || echo "")
+        if [[ -n "$FIRST_ACTIVE_WT" ]]; then
+          # Predicate (a) canonical + (b) at least one active worktree
+          # is satisfied. Now check (c) mutation command keywords.
+          # Read-only commands (status, log, diff, show, fetch w/o --prune,
+          # rev-parse, ls-files, branch -v, stash list) are NOT in this
+          # set; they fall through to the existing guard rules.
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+checkout\s+[^[:space:]-]'; then
+            canonical_guard_emit_block "git checkout (branch switch)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+switch\s+[^[:space:]-]'; then
+            canonical_guard_emit_block "git switch (branch switch)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+branch\s+(-f|--force)'; then
+            canonical_guard_emit_block "git branch -f (force branch update)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+          # git reset variants other than --hard (already covered later in
+          # this file) — --keep, --merge, --soft, --mixed, or with no
+          # mode flag — mutate the canonical's working tree/HEAD.
+          if echo "$COMMAND" | grep -qE '(^|[[:space:];&|])git\s+reset\b' \
+             && ! echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+            canonical_guard_emit_block "git reset (HEAD mutation)" "$FIRST_ACTIVE_WT"
+            exit 2
+          fi
+        fi
+      fi
+    fi
+  fi
+fi
+# ─── /CANONICAL-CHECKOUT-WORKTREE-GUARD-001 ──────────────────────────
+
 # Block cross-boundary file copies (worktree → main).
 WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
 if [[ -d "$WORKTREE_BASE" ]]; then