@paths.design/caws-cli 11.1.7 → 11.1.8

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: 5
+# hook_pack_version: 11
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`
@@ -124,4 +124,118 @@ for k, v in fields.items():
          HOOK_STOP_HOOK_ACTIVE="${HOOK_STOP_HOOK_ACTIVE:-0}" \
          HOOK_TOOL_INPUT_JSON="${HOOK_TOOL_INPUT_JSON:-{\}}" \
          HOOK_TOOL_RESPONSE_JSON="${HOOK_TOOL_RESPONSE_JSON:-{\}}"
+
+  # CAWS-SESSION-ID-DURABLE-HOOK-ENVELOPE-001: write/refresh the
+  # durable session envelope so agent-Bash CLI invocations (which
+  # don't inherit HOOK_SESSION_ID) can recover the harness session id
+  # via the on-disk bridge. Skipped when session id is missing/unknown
+  # (the resolver refuses literal "unknown" anyway). Non-fatal on any
+  # error — the hook must never block on this cache write.
+  _write_durable_session_envelope
+}
+
+# CAWS-SESSION-ID-DURABLE-HOOK-ENVELOPE-001
+# Write/refresh `<repo_root>/tmp/<session_id>/.session-envelope.json`.
+# Called from parse_hook_input after exports are set. Idempotent.
+# Preserves created_at across refreshes; updates last_seen_at to now.
+# All failures are silently swallowed; hooks MUST NOT block on cache.
+_write_durable_session_envelope() {
+  # Refuse missing/unknown/empty session id. The resolver refuses the
+  # literal "unknown" so writing it would just produce a stale file
+  # that gets skipped on read.
+  local sid="${HOOK_SESSION_ID:-}"
+  if [[ -z "$sid" || "$sid" == "unknown" ]]; then
+    return 0
+  fi
+
+  # Repo root via git. If HOOK_CWD is empty or git fails, skip — we
+  # can't write a repo-keyed envelope without one.
+  local cwd="${HOOK_CWD:-$PWD}"
+  local repo_root
+  repo_root=$(cd "$cwd" 2>/dev/null && git rev-parse --show-toplevel 2>/dev/null) || return 0
+  [[ -z "$repo_root" ]] && return 0
+
+  local envelope_dir="$repo_root/tmp/$sid"
+  local envelope_path="$envelope_dir/.session-envelope.json"
+  mkdir -p "$envelope_dir" 2>/dev/null || return 0
+
+  # Preserve created_at from existing envelope (refresh semantics).
+  # Use python for JSON read; if parse fails, treat as new envelope.
+  local now created_at
+  now=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+  created_at="$now"
+  if [[ -f "$envelope_path" ]]; then
+    local existing_created
+    existing_created=$(python3 -c '
+import json, sys
+try:
+    with open(sys.argv[1]) as f:
+        d = json.load(f)
+    v = d.get("created_at")
+    if isinstance(v, str) and v:
+        print(v)
+except Exception:
+    pass
+' "$envelope_path" 2>/dev/null)
+    if [[ -n "$existing_created" ]]; then
+      created_at="$existing_created"
+    fi
+  fi
+
+  # Atomic write: temp file + rename. tmpfile is in the same dir to
+  # guarantee same-filesystem rename atomicity.
+  local tmpfile="$envelope_dir/.session-envelope.tmp.$$"
+  python3 -c '
+import json, sys
+payload = {
+    "session_id": sys.argv[1],
+    "repo_root": sys.argv[2],
+    "created_at": sys.argv[3],
+    "last_seen_at": sys.argv[4],
+    "hook_event": sys.argv[5],
+}
+with open(sys.argv[6], "w") as f:
+    json.dump(payload, f)
+    f.write("\n")
+' "$sid" "$repo_root" "$created_at" "$now" "${HOOK_EVENT_NAME:-unknown}" "$tmpfile" 2>/dev/null || {
+    rm -f "$tmpfile" 2>/dev/null
+    return 0
+  }
+  mv -f "$tmpfile" "$envelope_path" 2>/dev/null || {
+    rm -f "$tmpfile" 2>/dev/null
+    return 0
+  }
+
+  # CAWS-WORKTREE-OWNERSHIP-HARNESS-ID-001: also write/refresh the per-repo
+  # caller-session pointer at `<repo_root>/tmp/.caller-session.json`. In
+  # agent-Bash, HOOK_SESSION_ID is not in the env, so the resolver cannot
+  # tell which of several fresh sibling envelopes is the caller's. This
+  # pointer names the session that most recently fired a hook in this repo
+  # — the actively-working caller — so the resolver can disambiguate the
+  # >=2-fresh-envelope case to the caller's own envelope. Evidence only:
+  # the resolver treats absent/stale/non-matching pointers as "refuse",
+  # never as a guess. Reuses sid / repo_root / now from above.
+  local pointer_dir="$repo_root/tmp"
+  local pointer_path="$pointer_dir/.caller-session.json"
+  local pointer_tmp="$pointer_dir/.caller-session.tmp.$$"
+  mkdir -p "$pointer_dir" 2>/dev/null || return 0
+  python3 -c '
+import json, sys
+payload = {
+    "session_id": sys.argv[1],
+    "repo_root": sys.argv[2],
+    "last_seen_at": sys.argv[3],
+}
+with open(sys.argv[4], "w") as f:
+    json.dump(payload, f)
+    f.write("\n")
+' "$sid" "$repo_root" "$now" "$pointer_tmp" 2>/dev/null || {
+    rm -f "$pointer_tmp" 2>/dev/null
+    return 0
+  }
+  mv -f "$pointer_tmp" "$pointer_path" 2>/dev/null || {
+    rm -f "$pointer_tmp" 2>/dev/null
+    return 0
+  }
+  return 0
 }

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: 5
+# hook_pack_version: 11
 # 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/loc-delta-check.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 31
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# CAWS LOC-Delta Advisory Check (QG-HOOKS-EXTRACT-001)
+#
+# Advisory-only PostToolUse hook firing on Edit. Flags a single edit that adds
+# more than a configurable number of lines to one file — a refactoring-budget
+# signal (CLAUDE.md "Ask first for risky changes ... >300 LOC"). It NEVER
+# blocks, NEVER mutates, and does not depend on any quality-gates module.
+#
+# Delta source (priority order):
+#   1. Edit payload — newline-count(new_string) - newline-count(old_string).
+#      Exact, synchronous, works on untracked files and in worktrees where a
+#      git diff would be misleading. This is the primary source.
+#   2. If the payload lacks old_string/new_string (e.g. a Write or a multi-edit
+#      batch shape this hook doesn't model), exit 0 silently — an advisory
+#      hook must never produce a false positive from missing data.
+#
+# env:
+#   CAWS_LOC_DELTA_WARN_THRESHOLD   added-line threshold (default 300)
+
+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
+
+FILE_PATH="$HOOK_FILE_PATH"
+TOOL_NAME="$HOOK_TOOL_NAME"
+
+# Edit only — the LOC-delta signal is about growing an existing file.
+[[ "$TOOL_NAME" != "Edit" ]] && exit 0
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# Skip generated / vendored / build output.
+case "$FILE_PATH" in
+  */node_modules/* | */dist/* | */build/* | */coverage/* | */.next/* | */out/* | */vendor/*)
+    exit 0
+    ;;
+esac
+case "$(basename "$FILE_PATH")" in
+  *.min.js | *.bundle.js | *.map | *.lock | *-lock.json | package-lock.json)
+    exit 0
+    ;;
+esac
+
+THRESHOLD="${CAWS_LOC_DELTA_WARN_THRESHOLD:-300}"
+[[ "$THRESHOLD" =~ ^[0-9]+$ ]] || THRESHOLD=300
+
+# Need jq + the payload to read old_string/new_string.
+command -v jq >/dev/null 2>&1 || exit 0
+[[ -n "${HOOK_TOOL_INPUT_JSON:-}" ]] || exit 0
+
+# Presence check: only proceed if BOTH fields exist in the payload. A missing
+# field => exit silently (priority-2 rule: no false positives from missing data).
+HAS_OLD=$(printf '%s' "$HOOK_TOOL_INPUT_JSON" | jq -r 'has("old_string")' 2>/dev/null || printf 'false')
+HAS_NEW=$(printf '%s' "$HOOK_TOOL_INPUT_JSON" | jq -r 'has("new_string")' 2>/dev/null || printf 'false')
+[[ "$HAS_OLD" == "true" && "$HAS_NEW" == "true" ]] || exit 0
+
+# Line counts via jq: number of lines in each string. A string with N
+# newlines spans N+1 lines, but for an added-LOC delta the newline count is
+# the right comparator (it counts line-breaks introduced).
+OLD_LINES=$(printf '%s' "$HOOK_TOOL_INPUT_JSON" | jq -r '(.old_string // "") | (. / "\n" | length) - 1' 2>/dev/null || printf '0')
+NEW_LINES=$(printf '%s' "$HOOK_TOOL_INPUT_JSON" | jq -r '(.new_string // "") | (. / "\n" | length) - 1' 2>/dev/null || printf '0')
+
+# Normalize to integers; an empty string yields -1 from the formula above,
+# clamp to 0.
+[[ "$OLD_LINES" =~ ^-?[0-9]+$ ]] || OLD_LINES=0
+[[ "$NEW_LINES" =~ ^-?[0-9]+$ ]] || NEW_LINES=0
+(( OLD_LINES < 0 )) && OLD_LINES=0
+(( NEW_LINES < 0 )) && NEW_LINES=0
+
+DELTA=$(( NEW_LINES - OLD_LINES ))
+
+if (( DELTA > THRESHOLD )); then
+  MSG="LOC-delta advisory: this edit to ${FILE_PATH} adds ~${DELTA} lines (> ${THRESHOLD} threshold). Large single edits are hard to review and often signal that the change should be split into smaller, focused commits or that a new module is warranted. (Advisory only — set CAWS_LOC_DELTA_WARN_THRESHOLD to tune; this never blocks.)"
+  jq -n --arg msg "$MSG" '{
+    hookSpecificOutput: {
+      hookEventName: "PostToolUse",
+      additionalContext: $msg
+    }
+  }'
+fi
+
+exit 0

package/templates/hook-packs/claude-code/naming-check.sh

@@ -0,0 +1,128 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 25
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# CAWS Naming Convention Check Hook for Claude Code
+#
+# Advisory-only PostToolUse hook that fires on Write (new file creation
+# only). Flags filenames that violate the "no shadow files" doctrine
+# stated in CLAUDE.md:
+#
+#   - Banned modifier suffixes (enhanced, unified, simplified, new,
+#     next, final, copy, revamp, improved, alt, tmp, scratch, wip,
+#     temp, old, backup, plus test-variant equivalents)
+#   - Version suffixes (-v2., _v3., etc.) — git is the version
+#     control surface, not filenames
+#   - Date stamps (YYYY-MM-DD) — same reason
+#
+# Test files with canonical extensions (.test.js, .spec.ts, etc.)
+# are explicitly exempted from the test-related modifier checks.
+#
+# Promoted from Sterling per CAWS-HOOK-PACK-PROMOTE-001. The advisory
+# messages have been genericized: removed Sterling-era references to
+# the v10 `caws naming check` CLI command (which v11 does not ship)
+# and to `.caws/canonical-map.yaml` (a v10 artifact). The doctrine
+# the hook enforces remains: CLAUDE.md key rule "No shadow files —
+# edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`
+# copies".
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+parse_hook_input
+
+FILE_PATH="$HOOK_FILE_PATH"
+TOOL_NAME="$HOOK_TOOL_NAME"
+
+# Only check Write tool (new files)
+if [[ "$TOOL_NAME" != "Write" ]]; then
+  exit 0
+fi
+
+if [[ -z "$FILE_PATH" ]]; then
+  exit 0
+fi
+
+# Get filename
+FILENAME=$(basename "$FILE_PATH")
+
+# Banned modifiers that indicate incomplete/temporary naming
+BANNED_MODIFIERS=(
+  "enhanced"
+  "unified"
+  "simplified"
+  "better"
+  "new"
+  "next"
+  "final"
+  "copy"
+  "revamp"
+  "improved"
+  "alt"
+  "tmp"
+  "scratch"
+  "wip"
+  "test-"
+  "-test"
+  "_test"
+  "temp"
+  "old"
+  "backup"
+)
+
+# Convert filename to lowercase for checking
+FILENAME_LOWER=$(echo "$FILENAME" | tr '[:upper:]' '[:lower:]')
+
+# Check for banned modifiers (word-boundary aware)
+for modifier in "${BANNED_MODIFIERS[@]}"; do
+  # Use word-boundary matching to avoid false positives (e.g., "old" in "gold_oracle")
+  # Match modifier preceded by start-of-string, hyphen, or underscore
+  # and followed by end-of-string, hyphen, underscore, or dot
+  if [[ "$FILENAME_LOWER" =~ (^|[-_.])"$modifier"([-_.]|$) ]]; then
+    # Special case: allow test files that follow conventions
+    if [[ "$modifier" == "test-" ]] || [[ "$modifier" == "-test" ]] || [[ "$modifier" == "_test" ]]; then
+      if [[ "$FILENAME_LOWER" =~ \.(test|spec)\.(js|ts|jsx|tsx|py|go|rs)$ ]]; then
+        continue
+      fi
+    fi
+
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PostToolUse",
+        "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains the modifier '\'''"$modifier"''\'' which may indicate temporary or non-canonical naming. Per the CAWS doctrine (CLAUDE.md key rule \"No shadow files\"), edit existing files in place rather than creating *-enhanced.*, *-new.*, *-v2.* copies. Consider using a more descriptive, permanent name."
+      }
+    }'
+    exit 0
+  fi
+done
+
+# Check for version suffixes (e.g., file-v2.js, file_v3.ts)
+if [[ "$FILENAME_LOWER" =~ [-_]v[0-9]+\. ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a version suffix. Version control should be handled by git, not file names. Consider removing the version suffix."
+    }
+  }'
+  exit 0
+fi
+
+# Check for date stamps (e.g., file-2024-01-15.js)
+if [[ "$FILENAME_LOWER" =~ [0-9]{4}[-_][0-9]{2}[-_][0-9]{2} ]]; then
+  echo '{
+    "hookSpecificOutput": {
+      "hookEventName": "PostToolUse",
+      "additionalContext": "Warning: The filename '\'''"$FILENAME"''\'' contains a date stamp. Version control should be handled by git, not file names. Consider removing the date."
+    }
+  }'
+  exit 0
+fi
+
+# File naming is OK
+exit 0

package/templates/hook-packs/claude-code/plan-transcript-finalize.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 27
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# Plan Transcript Finalize — overwrite each pending plan-transcript
+# snapshot with the final turn-end transcript.
+#
+# Wired into: Stop dispatch.
+#
+# At hook time:
+#   - The agent's turn is ending. The transcript at $TRANSCRIPT_PATH
+#     now includes everything that happened: the agent's plan,
+#     ExitPlanMode presentation, user approval/rejection, and any
+#     subsequent reasoning or tool calls.
+#   - $HOME/.claude/.pending-plan-snapshots lists snapshot paths that
+#     plan-transcript-snapshot.sh registered earlier in this turn.
+#   - For each pending snapshot, overwrite with the final transcript
+#     so the file co-located next to the plan represents the FULL
+#     conversation context that produced + reviewed the plan.
+#   - Drain the pending list (the snapshots are now finalized; future
+#     plan presentations in future turns get fresh entries).
+#
+# Idempotency: this hook is safe to run multiple times. If the pending
+# list is empty or doesn't exist, the hook is a no-op.
+#
+# Companion: plan-transcript-snapshot.sh (PostToolUse on ExitPlanMode)
+# is the producer. Both ship together per CAWS-HOOK-PACK-PROMOTE-001.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+parse_hook_input
+
+TRANSCRIPT_PATH="$HOOK_TRANSCRIPT_PATH"
+[ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ] || exit 0
+
+PENDING="$HOME/.claude/.pending-plan-snapshots"
+[ -f "$PENDING" ] || exit 0
+
+# Process each pending snapshot. Order doesn't matter — each is just
+# a file copy. Skip empty lines defensively.
+while IFS= read -r snapshot; do
+    [ -z "$snapshot" ] && continue
+    snapshot_dir=$(dirname "$snapshot")
+    [ -d "$snapshot_dir" ] || continue
+    cp "$TRANSCRIPT_PATH" "$snapshot" 2>/dev/null || true
+done < "$PENDING"
+
+# Drain the pending list. New ExitPlanMode calls in subsequent turns
+# will re-populate it via plan-transcript-snapshot.sh.
+> "$PENDING" 2>/dev/null || true
+
+exit 0

package/templates/hook-packs/claude-code/plan-transcript-snapshot.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 27
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# Plan Transcript Snapshot — capture conversation context at the moment
+# the agent presents a plan via ExitPlanMode.
+#
+# Wired into: PostToolUse with matcher "ExitPlanMode" (self-filters on
+# $HOOK_TOOL_NAME at the top).
+#
+# At hook time:
+#   - The agent has finished building the plan (Write/Edit calls done).
+#   - ExitPlanMode has just been called to present the plan to the user.
+#   - The transcript at $TRANSCRIPT_PATH contains everything up to this
+#     moment: exploration, design, tool results, the plan-write itself,
+#     and the ExitPlanMode tool_use record.
+#   - The user's approval/rejection and any subsequent reasoning are NOT
+#     yet in the transcript — those come later in the turn and are
+#     captured by plan-transcript-finalize.sh on Stop.
+#
+# Output:
+#   - <plan-path>.transcript.jsonl  — co-located transcript snapshot.
+#   - $HOME/.claude/.pending-plan-snapshots — newline-separated list of
+#     snapshot paths awaiting Stop-hook finalization (overwrite with
+#     the final transcript at turn end).
+#
+# Privacy note: The transcript is unfiltered. It includes Bash command
+# outputs, Read results, and any content that crossed the conversation.
+# Sharing the .transcript.jsonl file is equivalent to sharing your full
+# session for the turns leading up to the plan. Treat accordingly.
+#
+# Companion: plan-transcript-finalize.sh (Stop hook) drains the pending
+# list and finalizes each snapshot with the turn-end transcript.
+# Promoted from Sterling per CAWS-HOOK-PACK-PROMOTE-001.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+parse_hook_input
+
+# Hook gates — bail silently if anything is wrong rather than fail visibly.
+# A snapshot hook should never block the agent's flow.
+TOOL_NAME="$HOOK_TOOL_NAME"
+[ "$TOOL_NAME" = "ExitPlanMode" ] || exit 0
+
+TRANSCRIPT_PATH="$HOOK_TRANSCRIPT_PATH"
+[ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ] || exit 0
+
+# Find the most recent plan file Write in the transcript. The transcript
+# is a JSONL stream of conversation events; grep is cheaper and more
+# robust than jq for this lookup since field nesting can vary across
+# Claude Code versions. Match: "file_path":"/.../.claude/plans/<name>.md"
+#
+# `|| true` swallows grep's exit-1 on no-match so set -e doesn't abort
+# the script before our bail-out check runs.
+PLAN_FILE=$(grep -oE '"file_path":"[^"]*/\.claude/plans/[^"]*\.md"' "$TRANSCRIPT_PATH" 2>/dev/null \
+    | tail -1 \
+    | sed -E 's/^"file_path":"//; s/"$//' \
+    || true)
+
+[ -n "$PLAN_FILE" ] && [ -f "$PLAN_FILE" ] || exit 0
+
+# Snapshot at this moment (plan finalized + presented).
+SNAPSHOT="${PLAN_FILE%.md}.transcript.jsonl"
+cp "$TRANSCRIPT_PATH" "$SNAPSHOT" 2>/dev/null || exit 0
+
+# Mark for Stop-hook finalization. The finalize hook will overwrite the
+# snapshot with the FINAL turn-end transcript (which includes user
+# approval, any subsequent reasoning, and the rest of the turn).
+PENDING="$HOME/.claude/.pending-plan-snapshots"
+mkdir -p "$(dirname "$PENDING")" 2>/dev/null || true
+
+# Idempotent append: don't duplicate if already pending. Multiple
+# ExitPlanMode calls in one session targeting the same plan file
+# overwrite the snapshot but only register the snapshot path once.
+if [ ! -f "$PENDING" ] || ! grep -qxF "$SNAPSHOT" "$PENDING" 2>/dev/null; then
+    echo "$SNAPSHOT" >> "$PENDING"
+fi
+
+exit 0

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

@@ -0,0 +1,59 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 8,16,23
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# CAWS Protected Paths Guard for Claude Code
+#
+# Blocks direct Write/Edit access to:
+#   - hook scripts under .claude/hooks/* (no agent-side hook editing)
+#   - strike-state files .claude/logs/guard-strikes-*.json (no manual
+#     manipulation of progressive-strike counters)
+#
+# This is the structural enforcement of the doctrine that hooks
+# "may not be removed or weakened by an agent's local judgment"
+# (templates/hook-packs/claude-code/CLAUDE.md). Promoted from Sterling
+# per CAWS-HOOK-PACK-PROMOTE-001.
+#
+# 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.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+parse_hook_input
+
+case "$HOOK_TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+if [[ -z "$HOOK_FILE_PATH" ]]; then
+  exit 0
+fi
+
+case "$HOOK_FILE_PATH" in
+  */.claude/hooks/*)
+    echo "BLOCKED: $HOOK_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: $HOOK_FILE_PATH is protected guard state." >&2
+    echo "Do not edit strike counters by hand to bypass enforcement." >&2
+    echo "If the scope was legitimately corrected and prior strikes are stale, ask the user to run:" >&2
+    echo "  bash .claude/hooks/reset-strikes.sh --current" >&2
+    echo "(or --session <uuid> / --worktree <name> / --all --confirm; resets are logged)." >&2
+    echo "Otherwise switch into the correct worktree, update the active CAWS spec scope, or ask the user for direction." >&2
+    exit 2
+    ;;
+esac
+
+exit 0

package/templates/hook-packs/claude-code/quiet-merge.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 11
+# caws_min_major: 11
+# lineage_refs: 22,26
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# Quiet merge hook: suppress verbose output AND fix CWD safety
+#
+# Two problems solved:
+# 1. `caws worktree merge` produces verbose output that can overflow context.
+# 2. When a subagent's CWD is inside the worktree being destroyed, the process
+#    loses its CWD and crashes (posix_spawn ENOENT on PostToolUse hooks).
+#
+# The fix: rewrite merge/destroy commands to:
+#   cd <repo-root> && <command> 2>/dev/null | tail -3
+# This moves CWD to safety BEFORE the directory is destroyed, and suppresses
+# verbose output.
+#
+# IMPORTANT: This hook MUST be the last PreToolUse hook for Bash commands
+# that intercepts input. It emits updatedInput which replaces any prior
+# hook's updatedInput. Order in dispatch/pre_tool_use.sh: after the
+# blocking guards (so a real refusal still fires), before scan-secrets
+# (which is advisory-only and emits additionalContext, not updatedInput).
+#
+# Promoted from Sterling per CAWS-HOOK-PACK-PROMOTE-001 and
+# docs/reports/sterling_hook_port_audit_001.md. Companion to cwd-guard.sh
+# (entry 22) for the worktree-destroyed-while-inside class.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+parse_hook_input
+
+TOOL_NAME="$HOOK_TOOL_NAME"
+COMMAND="$HOOK_COMMAND"
+
+# Only intercept Bash tool
+if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# Resolve repo root (may differ from CLAUDE_PROJECT_DIR in worktrees)
+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
+
+# Match: caws worktree merge|destroy <name> [options]
+# Skip if already piped/redirected (user already handling output)
+if echo "$COMMAND" | grep -qE 'caws\s+worktree\s+(merge|destroy)\b' && ! echo "$COMMAND" | grep -qE '[|>]'; then
+  # Always prepend cd to repo root for CWD safety (critical for subagents
+  # whose CWD is inside the worktree being destroyed)
+  QUIET_CMD="cd \"$PROJECT_DIR\" && $COMMAND 2>/dev/null | tail -3; echo '---'; git log --oneline -1"
+  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","updatedInput":{"command":%s}}}' "$(printf '%s' "$QUIET_CMD" | jq -Rs .)"
+  exit 0
+fi
+
+exit 0

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: 5
+# hook_pack_version: 11
 # 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: 5
+# hook_pack_version: 11
 # 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: 5
+# hook_pack_version: 11
 # caws_min_major: 11
 # lineage_refs: 8,16
 # do_not_edit_directly: update via `caws init --agent-surface claude-code`