@paths.design/caws-cli 11.1.5 → 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`