@paths.design/caws-cli 11.1.5 → 11.1.7

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

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

@@ -1,21 +1,37 @@
 #!/bin/bash
 # CAWS-MANAGED-HOOK
 # hook_pack: claude-code
-# hook_pack_version: 2
+# hook_pack_version: 5
 # caws_min_major: 11
 # lineage_refs: 4,8,13
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
 #
-# CAWS Worktree Write Guard for Claude Code (v11-shape, intentionally
-# fail-open for v11.1).
+# CAWS Worktree Write Guard for Claude Code.
 #
-# This hook fires on Write/Edit and currently allows all writes from the
-# main checkout. Worktree-first enforcement returns when worktree lifecycle
-# is restored in CLI-WORKTREE-001 (Slice 6). Until then, this hook serves
-# as the managed-install seat for the worktree-write enforcement surface
-# and asserts the always-allowed allowlist so .caws/, .claude/, docs/,
-# scripts/, tmp/, and tests/ writes are never inadvertently blocked by a
-# future enforcement pass that forgets the allowlist.
+# Two responsibilities:
+#
+#   1. Canonical-spec-materialization refusal
+#      (WORKTREE-SPEC-CANONICAL-ACCESS-GUARD-001 A1/A2).
+#      From inside a linked worktree (git rev-parse --git-common-dir !=
+#      git rev-parse --git-dir, after realpath normalization), refuse
+#      Read/Write/Edit tool calls whose file_path resolves under
+#      <linked-worktree>/.caws/specs/*. Such files would be private
+#      materialized copies of canonical spec authority, divergent from
+#      the canonical .caws/specs bytes, silently consulted by anything
+#      that walks cwd upward. The refusal MUST fire BEFORE the broad
+#      .caws/* allowlist below, otherwise the allowlist would exit 0
+#      first and the slice would appear implemented while the target
+#      path still bypassed the guard. The canonical checkout itself
+#      (git_common_dir == git_dir) IS spec authority and is allowed
+#      through this predicate; this refusal targets the linked-worktree
+#      materialization class only.
+#
+#   2. Base-branch write enforcement (intentionally fail-open for
+#      v11.1, restored in CLI-WORKTREE-001). The hook serves as the
+#      managed-install seat for the worktree-write enforcement surface
+#      and asserts the always-allowed allowlist so .caws/, .claude/,
+#      docs/, scripts/, tmp/, and tests/ writes are never inadvertently
+#      blocked by a future enforcement pass that forgets the allowlist.
 #
 # Worktree-active enforcement (when restored) must read the worktrees
 # registry under both shapes:
@@ -34,23 +50,122 @@ TOOL_NAME="$HOOK_TOOL_NAME"
 FILE_PATH="$HOOK_FILE_PATH"
 
 case "$TOOL_NAME" in
-  Write|Edit) ;;
+  Read|Write|Edit) ;;
   *) exit 0 ;;
 esac
 
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd || printf '%s\n' "$PROJECT_DIR")"
+# WORKTREE_ROOT: where the agent is operating from. This is the cwd
+# whose .caws/specs/* path is the refusal target. Kept distinct from
+# CANONICAL_ROOT below — these MUST NOT be conflated for the spec-path
+# predicate.
+WORKTREE_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+WORKTREE_ROOT="$(cd "$WORKTREE_ROOT" 2>/dev/null && pwd -P || printf '%s\n' "$WORKTREE_ROOT")"
 
+# _realpath: best-effort realpath. macOS lacks `readlink -f` by default;
+# python3 is available on every supported runner (CI matrix verified).
+# Falls back to the original path if realpath cannot resolve.
+_realpath() {
+  local p="$1"
+  if [[ -z "$p" ]]; then
+    printf '%s\n' ""
+    return 0
+  fi
+  if command -v python3 >/dev/null 2>&1; then
+    python3 -c "import os, sys; print(os.path.realpath(sys.argv[1]))" "$p" 2>/dev/null || printf '%s\n' "$p"
+  else
+    printf '%s\n' "$p"
+  fi
+}
+
+# Linked-worktree detection via git as primary signal. CAWS registry
+# (.caws/worktrees.json) is consulted ONLY for diagnostic enrichment;
+# a registry desync MUST NOT suppress the refusal (I3).
+IS_LINKED_WORKTREE=0
+CANONICAL_ROOT=""
 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"
+  GIT_COMMON_DIR_RAW="$(cd "$WORKTREE_ROOT" 2>/dev/null && git rev-parse --git-common-dir 2>/dev/null || printf '')"
+  GIT_DIR_RAW="$(cd "$WORKTREE_ROOT" 2>/dev/null && git rev-parse --git-dir 2>/dev/null || printf '')"
+  if [[ -n "$GIT_COMMON_DIR_RAW" ]] && [[ -n "$GIT_DIR_RAW" ]]; then
+    # Resolve relative paths against WORKTREE_ROOT before realpath.
+    case "$GIT_COMMON_DIR_RAW" in
+      /*) GIT_COMMON_DIR_ABS="$GIT_COMMON_DIR_RAW" ;;
+      *)  GIT_COMMON_DIR_ABS="$WORKTREE_ROOT/$GIT_COMMON_DIR_RAW" ;;
+    esac
+    case "$GIT_DIR_RAW" in
+      /*) GIT_DIR_ABS="$GIT_DIR_RAW" ;;
+      *)  GIT_DIR_ABS="$WORKTREE_ROOT/$GIT_DIR_RAW" ;;
+    esac
+    GIT_COMMON_DIR="$(_realpath "$GIT_COMMON_DIR_ABS")"
+    GIT_DIR="$(_realpath "$GIT_DIR_ABS")"
+    if [[ -n "$GIT_COMMON_DIR" ]] && [[ "$GIT_COMMON_DIR" != "$GIT_DIR" ]]; then
+      IS_LINKED_WORKTREE=1
+      # CANONICAL_ROOT = parent of GIT_COMMON_DIR. Used for allowlist
+      # rewriting only; NOT used for the spec-path refusal predicate.
+      CANONICAL_CANDIDATE="$(_realpath "$GIT_COMMON_DIR/..")"
+      if [[ -n "$CANONICAL_CANDIDATE" ]] && [[ -d "$CANONICAL_CANDIDATE/.caws" ]]; then
+        CANONICAL_ROOT="$CANONICAL_CANDIDATE"
+      fi
     fi
   fi
 fi
 
+# Canonical-spec-materialization refusal (I1: BEFORE the allowlist).
+#
+# Predicate: tool_name in {Read,Write,Edit} (already gated above)
+#            AND is_linked_worktree (via git signal)
+#            AND FILE_PATH resolves under <WORKTREE_ROOT>/.caws/specs/.
+#
+# WORKTREE_ROOT is the cwd-as-resolved-via-CLAUDE_PROJECT_DIR. NOT
+# CANONICAL_ROOT, NOT a PROJECT_DIR that has been rewritten upward. The
+# refused path lives under the LINKED worktree's tree.
+if [[ "$IS_LINKED_WORKTREE" == "1" ]] && [[ -n "$FILE_PATH" ]]; then
+  # WORKTREE_ROOT is already realpath-normalized (pwd -P above), so
+  # SPEC_ROOT inherits that normalization. We MUST also normalize
+  # FILE_PATH_ABS through _realpath so the comparison is symlink-
+  # immune. On macOS, /tmp -> /private/tmp; without normalization, an
+  # agent-supplied /tmp/.../.caws/specs/X.yaml would NOT prefix-match
+  # SPEC_ROOT=/private/tmp/.../.caws/specs because the literal strings
+  # diverge. python3 os.path.realpath resolves the existing prefix
+  # even when the leaf does not exist (Write tool case).
+  SPEC_ROOT="$WORKTREE_ROOT/.caws/specs"
+  case "$FILE_PATH" in
+    /*) FILE_PATH_ABS="$FILE_PATH" ;;
+    *)  FILE_PATH_ABS="$WORKTREE_ROOT/$FILE_PATH" ;;
+  esac
+  FILE_PATH_ABS="$(_realpath "$FILE_PATH_ABS")"
+  case "$FILE_PATH_ABS" in
+    "$SPEC_ROOT"/*|"$SPEC_ROOT")
+      echo "[worktree-write-guard.sh] BLOCKED: $FILE_PATH" >&2
+      echo "[worktree-write-guard.sh] Refusing $TOOL_NAME against a linked-worktree .caws/specs/ path." >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] Linked worktrees must not use worktree-local .caws/specs/ files as authority." >&2
+      echo "[worktree-write-guard.sh] That path would be a private materialized copy, not canonical spec authority." >&2
+      echo "[worktree-write-guard.sh] CAWS resolves spec reads through the canonical control plane regardless of cwd." >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] To read a spec from any cwd (including this worktree), use:" >&2
+      echo "[worktree-write-guard.sh]   caws specs show <id>" >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] To check scope from any cwd, use:" >&2
+      echo "[worktree-write-guard.sh]   caws scope show <path>" >&2
+      echo "[worktree-write-guard.sh]   caws scope check <path>" >&2
+      echo "[worktree-write-guard.sh]" >&2
+      echo "[worktree-write-guard.sh] If sparse-checkout was disabled in this worktree and you need to restore" >&2
+      echo "[worktree-write-guard.sh] the canonical-only invariant, run from the canonical checkout:" >&2
+      echo "[worktree-write-guard.sh]   caws worktree repair-sparse <name>" >&2
+      exit 2
+      ;;
+  esac
+fi
+
+# Legacy allowlist preserved from v11.1 fail-open base-branch enforcement.
+# For the allowlist, use PROJECT_DIR rewritten toward the canonical checkout
+# (the historical behavior) so that .caws/ etc. paths under canonical also
+# match when the agent is operating from inside a linked worktree.
+PROJECT_DIR="$WORKTREE_ROOT"
+if [[ -n "$CANONICAL_ROOT" ]]; then
+  PROJECT_DIR="$CANONICAL_ROOT"
+fi
+
 # Always-allowed paths bypass any future enforcement.
 # User-global Claude state lives outside the repo; .caws/, .claude/, docs/,
 # scripts/, tmp/, .archive/, and .githooks/ are coordination/governance