@paths.design/caws-cli 11.1.0 → 11.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "11.1.0",
+  "version": "11.1.1",
   "description": "CAWS CLI - the governed core for CAWS project state, scope, claims, gates, waivers, and evidence (v11.1). Restores canonical spec/worktree lifecycle on the vNext kernel/store/shell architecture.",
   "main": "dist/index.js",
   "bin": {
@@ -9,7 +9,8 @@
   "preferGlobal": true,
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "templates/hook-packs/**"
   ],
   "scripts": {
     "build": "node scripts/build-cli.js",
@@ -33,7 +34,9 @@
     "validate": "echo 'CLI package validation not required'",
     "caws:validate": "node dist/index.js validate",
     "clean": "rm -rf dist test-caws-project .agent && npm run test:cleanup",
-    "prepare": "husky >/dev/null 2>&1 || true"
+    "prepare": "husky >/dev/null 2>&1 || true",
+    "smoke:fresh-install": "node scripts/fresh-install-smoke.mjs",
+    "prepublishOnly": "npm run build && node scripts/fresh-install-smoke.mjs"
   },
   "keywords": [
     "caws",

package/templates/hook-packs/claude-code/CLAUDE.md

@@ -0,0 +1,172 @@
+<!--
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 1,4,6,8,11,12,13,16,17
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+-->
+
+# CAWS Claude Code Hook Pack
+
+This directory contains the v11 Claude Code hook pack — pre-tool-call
+governance infrastructure that interposes between the agent and its Edit,
+Write, and Bash tools. The kernel/store/shell trinity owns canonical state;
+these hooks **project** that state into refusals at the agent's boundary,
+where the kernel cannot reach (the kernel runs downstream of the tool
+call).
+
+## The contract: every hook here exists because of an incident
+
+This pack is not optional scaffolding. Every script under
+`.claude/hooks/` traces to a specific entry in
+`packages/caws-cli/docs-status/failure-lineage.md`. Modifying or removing
+a hook requires:
+
+1. Naming the lineage entry the hook covers.
+2. Identifying the replacement mechanism that preserves the protection.
+3. Documenting the change in the same lineage doc.
+
+Hooks may be **evolved** as the v11 state model evolves. They may not be
+removed or weakened by an agent's local judgment. If you think a guard
+is wrong, stop and ask the user.
+
+## Lineage map
+
+| File | Lineage entries | What it prevents |
+|------|----------------|------------------|
+| `block-dangerous.sh` + `classify_command.py` | 1, 17 | catastrophic git operations; tokenized-argv bypasses; danger latch |
+| `worktree-guard.sh` | 4, 6, 11 | amend/stash/reset/force-push during active worktrees; cross-boundary file copies |
+| `worktree-write-guard.sh` | 4, 8, 13 | base-branch writes when worktrees are active (enforcement returns in CLI-WORKTREE-001); baseline-clobber |
+| `scope-guard.sh` | 8, 11, 12, 16 | edits outside the active spec's `scope.in`; cross-spec union interference; unbound → no authority |
+| `session-caws-status.sh` | 4, 11 | inherited-dirty-state collision; foreign-claim soft-block; version-skew |
+| `reset-strikes.sh` | 8, 16 | human-authorized strike reset (escape hatch, not auto-resettable) |
+| `reset-danger-latch.sh` | 17 | human-authorized danger latch reset |
+| `guard-strikes.sh` | 8, 16 | progressive enforcement (strike 1 warn → strike 3 block) |
+| `audit.sh` | 9 | per-tool-call audit log |
+| `session-log.sh` | 10 | per-turn narrative + structured transcripts |
+| `dispatch/*` | 8, 11, 17 | wires Claude Code's lifecycle to the registered handler list |
+| `lib/*` | 8, 16 | shared input parsing and handler runner |
+
+## v11 state-model awareness
+
+The v11 pack reads CAWS state under both v10 and v11 shapes during the
+transition window:
+
+- **Specs**: `lifecycle_state` is read first; `status` is the v10 fallback.
+  Terminal states (closed, archived, completed) are not enforced.
+  `draft` does NOT participate in union-wide blocking unless it is the
+  authoritative/bound spec.
+- **Worktrees registry**: both v11 direct-key
+  (`{"<name>": {...}}`) and v10 nested
+  (`{"worktrees": {"<name>": {...}}}`) shapes are accepted.
+- **Bound spec id**: both `entry.specId` (v10) and `entry.spec_id` (v11)
+  are accepted.
+
+## Version-skew warning
+
+`session-caws-status.sh` emits a non-blocking WARNING when the global
+`caws` binary's major version differs from the repo's `caws-cli` major
+version. Hooks parse local state directly, but any CLI advice in
+diagnostics may be invalid. Consider matching major versions:
+`npm install -g @paths.design/caws-cli@^<repo-major>`.
+
+## Activation
+
+Claude Code reads `.claude/settings.json` at session start. Installing
+the pack mid-session does NOT activate it until the session is restarted.
+`caws init --agent-surface claude-code` prints an activation instruction
+saying so. Do not continue substantive work after install without
+restarting first; the hooks you just installed are not yet enforcing.
+
+## settings.json wiring
+
+The pack does NOT manage `.claude/settings.json` — that file commonly
+carries user-authored `permissions` and `env` blocks that the pack
+should not overwrite. If you do not have a `.claude/settings.json`, add
+the following minimum configuration so the dispatch entrypoints fire on
+the Claude Code lifecycle:
+
+```jsonc
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash|Read|Write|Edit|Glob|Grep|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch/pre_tool_use.sh",
+            "timeout": 45
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|Bash|ExitPlanMode",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch/post_tool_use.sh",
+            "timeout": 60
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch/session_start.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/dispatch/stop.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-log.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Managed file headers
+
+Every managed file in this pack carries a header like:
+
+```
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: <N>
+# caws_min_major: 11
+# lineage_refs: <comma-separated entries>
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+```
+
+The header is what `caws init` uses to distinguish managed files (safe to
+update on re-install under a documented policy) from local user files
+(refused without explicit `--adopt` or `--overwrite`).
+
+Removing or editing the header turns the file into an unmanaged
+snowflake. Re-running install will then refuse to touch it — by design.

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

@@ -0,0 +1,121 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 9
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# CAWS Audit Hook for Claude Code
+# Logs agent actions for compliance and debugging
+# @author @darianrosebrook
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/parse-input.sh
+source "$SCRIPT_DIR/lib/parse-input.sh"
+
+# --- CWD resilience ---
+# PostToolUse hooks fire AFTER the command runs. If the command destroyed
+# the working directory (e.g., caws worktree merge deletes the worktree),
+# the hook process inherits a nonexistent CWD and most commands will fail.
+# Recover to a safe directory before doing anything else.
+if ! pwd >/dev/null 2>&1 || [ ! -d "$(pwd 2>/dev/null || echo __gone__)" ]; then
+  cd "${CLAUDE_PROJECT_DIR:-$HOME}" 2>/dev/null || cd "$HOME"
+fi
+
+parse_hook_input
+
+# Get event type from argument or input
+EVENT_TYPE="${1:-tool-use}"
+
+# Back-compat aliases. HOOK_CWD can be "" when stdin lacks a cwd field;
+# audit.sh always wants a non-empty placeholder so jq --arg stays happy.
+SESSION_ID="$HOOK_SESSION_ID"
+CWD="${HOOK_CWD:-.}"
+HOOK_EVENT="${HOOK_EVENT_NAME:-unknown}"
+TOOL_NAME="$HOOK_TOOL_NAME"
+PERMISSION_MODE="$HOOK_PERMISSION_MODE"
+
+# Ensure log directory exists
+LOG_DIR="${CLAUDE_PROJECT_DIR:-.}/.claude/logs"
+mkdir -p "$LOG_DIR"
+
+# Log file path
+LOG_FILE="$LOG_DIR/audit.log"
+DATE_LOG_FILE="$LOG_DIR/audit-$(date +%Y-%m-%d).log"
+
+# Timestamp
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Build log entry based on event type
+case "$EVENT_TYPE" in
+  session-start)
+    SOURCE="${HOOK_SOURCE:-unknown}"
+    MODEL="${HOOK_MODEL:-unknown}"
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "session_start" \
+      --arg source "$SOURCE" \
+      --arg model "$MODEL" \
+      --arg cwd "$CWD" \
+      '{timestamp: $ts, session_id: $sid, event: $event, source: $source, model: $model, cwd: $cwd}')
+    ;;
+
+  stop)
+    # HOOK_STOP_HOOK_ACTIVE is "0" or "1"; jq --argjson needs true/false.
+    if [[ "$HOOK_STOP_HOOK_ACTIVE" == "1" ]]; then
+      STOP_HOOK_ACTIVE="true"
+    else
+      STOP_HOOK_ACTIVE="false"
+    fi
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "session_stop" \
+      --arg cwd "$CWD" \
+      --argjson hook_active "$STOP_HOOK_ACTIVE" \
+      '{timestamp: $ts, session_id: $sid, event: $event, cwd: $cwd, stop_hook_active: $hook_active}')
+    ;;
+
+  tool-use)
+    # Tool-specific info lifted from HOOK_* env vars set by parse_hook_input.
+    # HOOK_TOOL_INPUT_JSON and HOOK_TOOL_RESPONSE_JSON are pre-serialized
+    # JSON strings, always valid (empty "{}" at minimum), so jq --argjson
+    # below never trips on missing fields.
+    TOOL_INPUT="$HOOK_TOOL_INPUT_JSON"
+    TOOL_RESPONSE="$HOOK_TOOL_RESPONSE_JSON"
+    TOOL_USE_ID="$HOOK_TOOL_USE_ID"
+    FILE_PATH="$HOOK_FILE_PATH"
+    COMMAND="$HOOK_COMMAND"
+
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "tool_use" \
+      --arg tool "$TOOL_NAME" \
+      --arg file "$FILE_PATH" \
+      --arg cmd "$COMMAND" \
+      --arg cwd "$CWD" \
+      --arg mode "$PERMISSION_MODE" \
+      '{timestamp: $ts, session_id: $sid, event: $event, tool: $tool, file: $file, command: $cmd, cwd: $cwd, permission_mode: $mode}')
+    ;;
+
+  *)
+    LOG_ENTRY=$(jq -n \
+      --arg ts "$TIMESTAMP" \
+      --arg sid "$SESSION_ID" \
+      --arg event "$EVENT_TYPE" \
+      --arg hook "$HOOK_EVENT" \
+      --arg cwd "$CWD" \
+      '{timestamp: $ts, session_id: $sid, event: $event, hook_event: $hook, cwd: $cwd}')
+    ;;
+esac
+
+# Append to log files
+echo "$LOG_ENTRY" >> "$LOG_FILE"
+echo "$LOG_ENTRY" >> "$DATE_LOG_FILE"
+
+# Success - allow operation to continue
+exit 0

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

@@ -0,0 +1,158 @@
+#!/bin/bash
+# CAWS-MANAGED-HOOK
+# hook_pack: claude-code
+# hook_pack_version: 2
+# caws_min_major: 11
+# lineage_refs: 1,17
+# do_not_edit_directly: update via `caws init --agent-surface claude-code`
+# CAWS Command Safety Gate for Claude Code
+# Delegates to classify_command.py for robust command parsing and classification.
+# Falls back to bash pattern matching if Python is unavailable.
+#
+# The Python classifier handles:
+#   - Heredoc-aware parsing (won't false-positive on quoted dangerous commands)
+#   - Quoted-region stripping (echo "git reset --hard" is safe)
+#   - Pipeline-aware dangers (curl | sh)
+#   - Context-aware rm classification (safe prefixes vs dangerous targets)
+#   - Proper shell segmentation (&&, ||, ;, |)
+#
+# @author @darianrosebrook
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+danger_state_dir() {
+  local project_dir="${CLAUDE_PROJECT_DIR:-.}"
+  local state_dir="$project_dir/.claude/hooks/state"
+  mkdir -p "$state_dir"
+  printf '%s\n' "$state_dir"
+}
+
+danger_latch_file() {
+  local session_id="$1"
+  local safe_session
+  safe_session=$(printf '%s' "$session_id" | tr -c 'A-Za-z0-9._-' '_')
+  printf '%s/danger-latch-%s.json\n' "$(danger_state_dir)" "$safe_session"
+}
+
+emit_block_json() {
+  local reason="$1"
+  jq -n --arg msg "$reason" '{ decision: "block", reason: $msg }'
+}
+
+emit_ask_json() {
+  local reason="$1"
+  jq -n --arg msg "$reason" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: $msg
+    }
+  }'
+}
+
+record_danger_latch() {
+  local file="$1"
+  local decision="$2"
+  local reason="$3"
+  local command="$4"
+
+  mkdir -p "$(dirname "$file")"
+  jq -n \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg hook "block-dangerous.sh" \
+    --arg decision "$decision" \
+    --arg reason "$reason" \
+    --arg command "$command" \
+    '{
+      ts: $ts,
+      hook: $hook,
+      decision: $decision,
+      reason: $reason,
+      command: $command,
+      message: "Dangerous command boundary engaged. User reset required before more Bash commands may run in this session."
+    }' > "$file"
+}
+
+# Read JSON input from Claude Code
+INPUT=$(cat)
+
+# Extract tool info
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""')
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""')
+# Fallback to "unknown" when no session id is available so the latch still
+# engages. Multiple concurrent sessions without an id will share the "unknown"
+# latch -- safer than not latching at all.
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // env.CLAUDE_SESSION_ID // env.HOOK_SESSION_ID // "unknown"')
+
+# Only check Bash tool
+if [[ "$TOOL_NAME" != "Bash" ]] || [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+LATCH_FILE="$(danger_latch_file "$SESSION_ID")"
+if [[ -f "$LATCH_FILE" ]]; then
+  REASON="A dangerous command was previously blocked or sent for approval in this Claude session. This is a human-review boundary, not a retryable syntax error. Do not rephrase, wrap, reorder, alias, or indirectly invoke the command. Ask the user to clear the latch with .claude/hooks/reset-danger-latch.sh before more Bash commands may run. Sentinel: $LATCH_FILE"
+  emit_block_json "$REASON"
+  exit 0
+fi
+
+# --- Python classifier (preferred path) ---
+CLASSIFIER="$SCRIPT_DIR/classify_command.py"
+if [[ ! -f "$CLASSIFIER" ]] || ! command -v python3 >/dev/null 2>&1; then
+  REASON="command classifier unavailable; dangerous-command safety cannot verify Bash semantics. This is a human-review boundary. Command was: $COMMAND"
+  record_danger_latch "$LATCH_FILE" "ask" "classifier unavailable" "$COMMAND"
+  emit_ask_json "$REASON"
+  exit 0
+fi
+
+REPO_ROOT="${CLAUDE_PROJECT_DIR:-.}"
+CLASSIFIER_STDERR=$(mktemp)
+RESULT=$(printf '%s' "$COMMAND" | python3 "$CLASSIFIER" \
+  --repo-root "$REPO_ROOT" \
+  --home "$HOME" \
+  --cwd "$(pwd)" 2>"$CLASSIFIER_STDERR") || {
+  DIAG=$(head -c 200 "$CLASSIFIER_STDERR" 2>/dev/null || true)
+  rm -f "$CLASSIFIER_STDERR"
+  RESULT="{\"decision\":\"ask\",\"reason\":\"command classifier failed: ${DIAG:-unknown error}\"}"
+}
+rm -f "$CLASSIFIER_STDERR"
+
+DECISION=$(printf '%s' "$RESULT" | jq -r '.decision // "ask"')
+REASON=$(printf '%s' "$RESULT" | jq -r '.reason // "unknown"')
+
+case "$DECISION" in
+  allow)
+    exit 0
+    ;;
+  deny)
+    FULL_REASON="$REASON. This is a HARD BLOCK — Claude Code will refuse the command. This is a human-review boundary, not a retryable syntax error. Do not rephrase, wrap, reorder, alias, or indirectly invoke this command (e.g. via 'command git ...', 'env ... git ...', 'bash -lc \"...\"', or 'git --bare init'). Stop and ask the user for the next step. Command was: $COMMAND"
+    record_danger_latch "$LATCH_FILE" "$DECISION" "$REASON" "$COMMAND"
+    emit_block_json "$FULL_REASON"
+    exit 0
+    ;;
+  ask)
+    FULL_REASON="$REASON. Claude Code will PAUSE and ask the user to approve before running. This may alter destructive or authority-bearing state. Do not attempt to bypass this by rephrasing the command, switching syntax, or wrapping the invocation. If permission is not granted, stop and ask the user for the next step. Command was: $COMMAND"
+    record_danger_latch "$LATCH_FILE" "$DECISION" "$REASON" "$COMMAND"
+    emit_ask_json "$FULL_REASON"
+    exit 0
+    ;;
+  *)
+    # Unknown decision value -- malformed classifier output. Do NOT fall
+    # through to the weaker regex fallback; ask+latch instead so a
+    # corrupted classifier cannot silently downgrade safety.
+    FULL_REASON="command classifier returned an unrecognized decision '$DECISION'. Claude Code will PAUSE and ask the user. This is a human-review boundary. Command was: $COMMAND"
+    record_danger_latch "$LATCH_FILE" "ask" "classifier unknown decision: $DECISION" "$COMMAND"
+    emit_ask_json "$FULL_REASON"
+    exit 0
+    ;;
+esac
+
+# Every classifier outcome (allow/deny/ask/unknown) exits inside the case
+# above. There is no flat-regex fallback; if classify_command.py cannot run,
+# the early-exit at the top of this script ask-latches the command. That
+# keeps the dangerous-command decision in a single semantic layer.
+
+# shellcheck disable=SC2317  # Defense-in-depth tail; unreachable on a healthy classifier.
+exit 0