@paths.design/caws-cli 11.0.0 → 11.1.1

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

@@ -0,0 +1,180 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 10
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# Session Logger for Claude Code — lean structured session capture.
+#
+# Canonical artifacts:
+#   session.json       — session index + aggregated refs + git snapshot
+#   turn-001.json      — per-turn detailed timeline
+#   handoff.json       — compact continuation view for follow-on agents
+#   session.txt        — human-readable summary pointing at the JSON artifacts
+#
+# Output: ./tmp/<session-id>/
+
+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
+
+SESSION_ID="$HOOK_SESSION_ID"
+HOOK_EVENT="${HOOK_EVENT_NAME:-unknown}"
+CWD="${HOOK_CWD:-.}"
+TRANSCRIPT_PATH="$HOOK_TRANSCRIPT_PATH"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+LOG_DIR="${CWD}/tmp/${SESSION_ID}"
+mkdir -p "$LOG_DIR"
+
+META_FILE="$LOG_DIR/.meta.json"
+RENDERER="$SCRIPT_DIR/session_log_renderer.py"
+
+resolve_transcript() {
+  if [[ -n "$TRANSCRIPT_PATH" ]] && [[ -f "$TRANSCRIPT_PATH" ]]; then
+    printf '%s\n' "$TRANSCRIPT_PATH"
+    return
+  fi
+
+  local slug candidate
+  slug=$(echo "$CWD" | sed 's|/|-|g; s|^-||')
+
+  candidate="$HOME/.claude/projects/${slug}/${SESSION_ID}.jsonl"
+  if [[ -f "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+    return
+  fi
+
+  candidate="$HOME/.claude/projects/-${slug}/${SESSION_ID}.jsonl"
+  if [[ -f "$candidate" ]]; then
+    printf '%s\n' "$candidate"
+    return
+  fi
+
+  printf '\n'
+}
+
+render_session_output() {
+  local transcript="$1"
+  local branch head_sha dirty_count started_at model start_sha
+
+  if cd "$CWD" 2>/dev/null && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+    head_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    dirty_count=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+  else
+    branch="unknown"
+    head_sha="unknown"
+    dirty_count="0"
+  fi
+
+  if [[ -f "$META_FILE" ]]; then
+    started_at=$(jq -r '.local_time // "unknown"' "$META_FILE")
+    model=$(jq -r '.model // "unknown"' "$META_FILE")
+    start_sha=$(jq -r '.head_sha // ""' "$META_FILE")
+  else
+    started_at="(resumed session)"
+    model="unknown"
+    start_sha=""
+  fi
+
+  python3 "$RENDERER" \
+    "$LOG_DIR" \
+    "$CWD" \
+    "$SESSION_ID" \
+    "$started_at" \
+    "$model" \
+    "$branch" \
+    "$head_sha" \
+    "$dirty_count" \
+    "$start_sha" \
+    "$transcript"
+}
+
+handle_session_start() {
+  local model source branch head_sha dirty_count full_time
+  model="${HOOK_MODEL:-unknown}"
+  source="${HOOK_SOURCE:-unknown}"
+  if cd "$CWD" 2>/dev/null && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+    head_sha=$(git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+    dirty_count=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+  else
+    branch="unknown"
+    head_sha="unknown"
+    dirty_count="0"
+  fi
+  full_time=$(date +"%Y-%m-%d %H:%M:%S %Z")
+
+  jq -cn \
+    --arg sid "$SESSION_ID" \
+    --arg ts "$TIMESTAMP" \
+    --arg lt "$full_time" \
+    --arg model "$model" \
+    --arg source "$source" \
+    --arg branch "$branch" \
+    --arg head "$head_sha" \
+    --arg dirty "$dirty_count" \
+    --arg project "$(basename "$CWD")" \
+    --arg transcript "$TRANSCRIPT_PATH" \
+    '{session_id: $sid, started_at: $ts, local_time: $lt, model: $model, source: $source, branch: $branch, head_sha: $head, dirty_files: $dirty, project: $project, transcript_path: $transcript}' \
+    > "$META_FILE"
+
+  render_session_output "$(resolve_transcript)"
+}
+
+handle_stop() {
+  render_session_output "$(resolve_transcript)"
+}
+
+handle_pre_compact() {
+  render_session_output "$(resolve_transcript)"
+}
+
+is_plan_file_path() {
+  local file_path
+  file_path="${1:-}"
+
+  [[ -n "$file_path" ]] || return 1
+
+  case "$file_path" in
+    "$HOME"/.claude/plans/*.md|*/.claude/plans/*.md)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+handle_post_tool_use() {
+  local tool_name file_path
+  tool_name="$HOOK_TOOL_NAME"
+  file_path="${HOOK_FILE_PATH:-}"
+  case "$tool_name" in
+    Write|Edit)
+      if is_plan_file_path "$file_path"; then
+        render_session_output "$(resolve_transcript)"
+      fi
+      ;;
+    ExitPlanMode)
+      render_session_output "$(resolve_transcript)"
+      ;;
+    *)
+      ;;
+  esac
+}
+
+case "$HOOK_EVENT" in
+  SessionStart) handle_session_start ;;
+  Stop) handle_stop ;;
+  PreCompact) handle_pre_compact ;;
+  PostToolUse) handle_post_tool_use ;;
+  *) ;;
+esac
+
+exit 0

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

@@ -0,0 +1,240 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 4,6,11
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+#
+# CAWS Worktree Safety Guard for Claude Code (v11-shape).
+# Blocks dangerous git operations and cross-boundary file copies when
+# parallel worktrees are active.
+#
+# Registry-shape compatibility:
+#   v11 direct-key: { "<name>": { "status": "active", ... } }
+#   v10 nested:     { "worktrees": { "<name>": { ... } } }
+
+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"
+
+if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+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
+
+# Block sparse checkout (runs before "only check git commands" early-exit)
+if echo "$COMMAND" | grep -qE 'caws\s+(worktree\s+create|parallel\s+setup).*--scope'; then
+  echo "BLOCKED: --scope (sparse checkout) is not allowed." >&2
+  echo "Sparse checkout breaks cross-module imports in most projects." >&2
+  echo "Use full worktrees without --scope. Scope enforcement comes from" >&2
+  echo "CAWS feature specs and lane discipline, not from hiding files." >&2
+  exit 2
+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
+  exit 2
+fi
+
+# Block cross-boundary file copies (worktree → main).
+WORKTREE_BASE="$PROJECT_DIR/.caws/worktrees"
+if [[ -d "$WORKTREE_BASE" ]]; then
+  if echo "$COMMAND" | grep -qE '\b(cp|mv)\b'; then
+    AGENT_IN_WORKTREE=false
+    if [[ -n "$HOOK_CWD" ]] && [[ "$HOOK_CWD" == "$WORKTREE_BASE"/* ]]; then
+      AGENT_IN_WORKTREE=true
+    fi
+
+    if [[ "$AGENT_IN_WORKTREE" != "true" ]]; then
+      if echo "$COMMAND" | grep -qF ".caws/worktrees/" || echo "$COMMAND" | grep -qF "$WORKTREE_BASE"; then
+        HAS_WT_PATH=false
+        HAS_MAIN_PATH=false
+        if echo "$COMMAND" | grep -qE '\.caws/worktrees/|'"$(echo "$WORKTREE_BASE" | sed 's/[\/&]/\\&/g')"''; then
+          HAS_WT_PATH=true
+        fi
+        if echo "$COMMAND" | grep -qE "(^|\s)$PROJECT_DIR/[^.]|core/|src/|tests/|packages/" && [[ "$HAS_WT_PATH" == "true" ]]; then
+          HAS_MAIN_PATH=true
+        fi
+        if [[ "$HAS_WT_PATH" == "true" ]] && [[ "$HAS_MAIN_PATH" == "true" ]]; then
+          echo "BLOCKED: Copying files from a worktree to the main repo is forbidden." >&2
+          echo "This bypasses worktree isolation. Work entirely within your worktree." >&2
+          echo "If tests need the main repo's venv, activate it with:" >&2
+          echo "  source $PROJECT_DIR/.venv/bin/activate" >&2
+          exit 2
+        fi
+      fi
+    fi
+  fi
+fi
+
+# Only check git commands from here on
+if ! echo "$COMMAND" | grep -qE '(^|\s|&&|\|)git\s'; then
+  exit 0
+fi
+
+# Determine if worktrees are active (dual-shape aware).
+#
+# Helper logic embedded in the Node inline reads worktrees.json under both
+# shapes. v11 direct-key: registry keys are worktree names themselves,
+# each value is an entry object with at least { status }. v10 nested:
+# registry.worktrees is the entry map.
+WORKTREES_ACTIVE=false
+PARALLEL_BASE=""
+
+if [[ -f "$PROJECT_DIR/.caws/parallel.json" ]] && command -v node >/dev/null 2>&1; then
+  PARALLEL_INFO=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/parallel.json', 'utf8'));
+      var agents = (reg.agents || []).length;
+      console.log(agents + ':' + (reg.baseBranch || ''));
+    } catch(e) { console.log('0:'); }
+  " 2>/dev/null || echo "0:")
+
+  AGENT_COUNT=$(echo "$PARALLEL_INFO" | cut -d: -f1)
+  PARALLEL_BASE=$(echo "$PARALLEL_INFO" | cut -d: -f2)
+
+  if [[ "$AGENT_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+if [[ "$WORKTREES_ACTIVE" != "true" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  ACTIVE_COUNT=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      // Dual-shape: v10 nested vs v11 direct-key.
+      function entriesOf(r) {
+        if (!r || typeof r !== 'object') return [];
+        if (r.worktrees && typeof r.worktrees === 'object') return Object.values(r.worktrees);
+        // v11 direct-key: filter to objects with a 'status' field to avoid
+        // mistaking top-level metadata (e.g., 'version') for an entry.
+        var out = [];
+        for (var k in r) {
+          if (Object.prototype.hasOwnProperty.call(r, k)) {
+            var v = r[k];
+            if (v && typeof v === 'object' && typeof v.status === 'string') out.push(v);
+          }
+        }
+        return out;
+      }
+      var entries = entriesOf(reg);
+      var active = entries.filter(function(w) { return w.status === 'active'; });
+      console.log(active.length);
+    } catch(e) { console.log('0'); }
+  " 2>/dev/null || echo "0")
+
+  if [[ "$ACTIVE_COUNT" -gt 0 ]] 2>/dev/null; then
+    WORKTREES_ACTIVE=true
+  fi
+fi
+
+if [[ "$WORKTREES_ACTIVE" != "true" ]]; then
+  exit 0
+fi
+
+# --- Block dangerous git operations when worktrees are active ---
+
+if echo "$COMMAND" | grep -qE 'git\s+commit\s+.*--amend'; then
+  echo "BLOCKED: git commit --amend is not allowed while worktrees are active." >&2
+  echo "Amending commits risks rewriting another agent's work." >&2
+  echo "Create a new commit instead." >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+stash' && ! echo "$COMMAND" | grep -qE 'git\s+stash\s+list'; then
+  echo "BLOCKED: git stash is not allowed while worktrees are active." >&2
+  echo "Stash is shared across all worktrees and can capture or destroy another agent's work." >&2
+  echo "Commit your changes to your branch instead." >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+reset\s+--hard'; then
+  echo "BLOCKED: git reset --hard is not allowed while worktrees are active." >&2
+  echo "This could discard work that other agents depend on." >&2
+  exit 2
+fi
+
+if echo "$COMMAND" | grep -qE 'git\s+push\s+.*(--force|-f\s)'; then
+  echo "BLOCKED: Force push is not allowed while worktrees are active." >&2
+  echo "This could rewrite history that other agents have based work on." >&2
+  exit 2
+fi
+
+# --- Base branch protections ---
+AGENT_DIR="${HOOK_CWD:-${CLAUDE_PROJECT_DIR:-.}}"
+CURRENT_BRANCH=$(cd "$AGENT_DIR" && git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+
+BASE_BRANCH="$PARALLEL_BASE"
+if [[ -z "$BASE_BRANCH" ]] && [[ -f "$PROJECT_DIR/.caws/worktrees.json" ]] && command -v node >/dev/null 2>&1; then
+  BASE_BRANCH=$(node -e "
+    try {
+      var reg = JSON.parse(require('fs').readFileSync('$PROJECT_DIR/.caws/worktrees.json', 'utf8'));
+      function entriesOf(r) {
+        if (!r || typeof r !== 'object') return [];
+        if (r.worktrees && typeof r.worktrees === 'object') return Object.values(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' && typeof v.status === 'string') out.push(v);
+          }
+        }
+        return out;
+      }
+      var entries = entriesOf(reg);
+      var active = entries.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 "")
+fi
+
+if [[ -n "$BASE_BRANCH" ]] && [[ "$CURRENT_BRANCH" == "$BASE_BRANCH" ]]; then
+  if echo "$COMMAND" | grep -qE 'git\s+push'; then
+    echo "BLOCKED: Pushing from the base branch ($BASE_BRANCH) while worktrees are active." >&2
+    echo "You should be working in a worktree, not on the base branch." >&2
+    echo "Use: cd .caws/worktrees/<name>/" >&2
+    exit 2
+  fi
+
+  if echo "$COMMAND" | grep -qE 'git\s+merge\b'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "Merging into base branch ('"$BASE_BRANCH"') while worktrees are active. The commit-msg hook will enforce the merge(worktree): message format. Make sure the worktree for this branch has been destroyed first."
+      }
+    }'
+    exit 0
+  fi
+
+  if echo "$COMMAND" | grep -qE 'git\s+commit\b' && ! echo "$COMMAND" | grep -qE '--amend'; then
+    echo '{
+      "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "additionalContext": "NOTE: committing to the base branch ('"$BASE_BRANCH"') while worktrees are active. Worktrees are preferred for isolated feature work, but logical checkpoint commits from the current checkout are allowed by Claude hooks. Avoid --amend and force-push while worktrees are active."
+      }
+    }'
+    exit 0
+  fi
+fi
+
+exit 0

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

@@ -0,0 +1,77 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# 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).
+#
+# 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.
+#
+# Worktree-active enforcement (when restored) must read the worktrees
+# registry under both shapes:
+#   v11 direct-key: { "<name>": { ... } }
+#   v10 nested:     { "worktrees": { "<name>": { ... } } }
+# and accept both specId (v10) and spec_id (v11) on entries.
+
+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"
+FILE_PATH="$HOOK_FILE_PATH"
+
+case "$TOOL_NAME" in
+  Write|Edit) ;;
+  *) exit 0 ;;
+esac
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+PROJECT_DIR="$(cd "$PROJECT_DIR" 2>/dev/null && pwd || printf '%s\n' "$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
+
+# 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
+# surfaces, not application code.
+if [[ -n "$FILE_PATH" ]]; then
+  case "$FILE_PATH" in
+    "${HOME:-}"/.claude/*) exit 0 ;;
+    "$PROJECT_DIR"/.caws/*|.caws/*) exit 0 ;;
+    "$PROJECT_DIR"/.claude/*|.claude/*) exit 0 ;;
+    "$PROJECT_DIR"/.gitignore|.gitignore) exit 0 ;;
+    "$PROJECT_DIR"/.tmp/*|.tmp/*) exit 0 ;;
+    "$PROJECT_DIR"/tmp/*|tmp/*) exit 0 ;;
+    "$PROJECT_DIR"/.archive/*|.archive/*) exit 0 ;;
+    "$PROJECT_DIR"/.githooks/*|.githooks/*) exit 0 ;;
+    "$PROJECT_DIR"/.github/*|.github/*) exit 0 ;;
+    "$PROJECT_DIR"/docs/*|docs/*) exit 0 ;;
+  esac
+fi
+
+# Fail-open until CLI-WORKTREE-001 (Slice 6) restores worktree lifecycle.
+# When that lands, this hook gains worktree-active enforcement using the
+# dual-shape registry helpers that scope-guard.sh and worktree-guard.sh
+# already use.
+exit 0