@iceinvein/agent-skills 0.18.2 → 0.19.0

package/skills/sluice/scripts/stop-guard.sh

@@ -45,13 +45,114 @@ fi
 
 cwd="$PWD"
 active="false"
+sid=""
+transcript=""
 if [ -n "$input" ]; then
 	got="$(printf '%s' "$input" | jq -r '.cwd // empty' 2>/dev/null || true)"
 	[ -n "$got" ] && cwd="$got"
 	active="$(printf '%s' "$input" | jq -r '.stop_hook_active // false' 2>/dev/null || echo false)"
+	sid="$(printf '%s' "$input" | jq -r '.session_id // empty' 2>/dev/null || true)"
+	transcript="$(printf '%s' "$input" | jq -r '.transcript_path // empty' 2>/dev/null || true)"
 fi
 [ "$active" = "true" ] && exit 0
 [ -d "$cwd" ] || exit 0
+
+# ---- entry check --------------------------------------------------------
+# The run guard below only arms once .sluice/run.json exists, and that file
+# only exists once the skill has been invoked. So the session that never
+# routed at all, the one this whole guard is for, walks straight past it in
+# silence. This catches that session from the other end: the tree moved while
+# it held it, and no channel was ever announced.
+#
+# The comparison is against where the tree stood when the session opened, not
+# against whether it is dirty now. A session that opens on someone's
+# work-in-progress and only answers questions changed nothing, and nudging it
+# would teach its partner to ignore the nudge.
+#
+# Refused once and then never again for this session: the check cannot tell
+# a partner who routed afterwards from one who read the nudge and chose to
+# carry on, and only the first of those is worth a second refusal.
+#
+# The stamp is per session and the tree it watches is not, so anything else
+# writing to the tree reads as this session's work: a second session, the
+# partner's own editor, an install touching a lockfile, a build emitting
+# something the tree does not ignore. There is nothing in a git tree that
+# attributes a change to who made it, so this is not fixable here, only
+# bounded: one refusal per session, and a reason that offers "not mine" as an
+# answer and takes it.
+entry_nudge() {
+	local stamps tree line_tree line_digest now
+	[ -n "$sid" ] || return 0
+	case "$sid" in */* | .*) return 0 ;; esac
+
+	# Two directories rather than one name and one suffixed name: sharing a
+	# namespace means a session id ending in `.nudged` silently disarms the
+	# session whose id is its prefix.
+	local root="${CLAUDE_CONFIG_DIR:-${HOME:-}/.claude}/sluice"
+	stamps="$root/stamps"
+	[ -f "$stamps/$sid" ] || return 0
+	[ -f "$root/nudged/$sid" ] && return 0
+
+	tree="$(git -C "$cwd" rev-parse --show-toplevel 2>/dev/null)" || return 0
+	[ -n "$tree" ] || return 0
+
+	line_tree="$(sed -n '1p' "$stamps/$sid" 2>/dev/null)"
+	line_digest="$(sed -n '2p' "$stamps/$sid" 2>/dev/null)"
+	[ -n "$line_tree" ] && [ -n "$line_digest" ] || return 0
+	# A session that moved trees carries a baseline for the one it left, and
+	# reading this tree's changes against it would be reading someone else's.
+	[ "$line_tree" = "$tree" ] || return 0
+
+	# A tree that cannot be read is unknown, not moved. Losing git's exit
+	# status here would turn a held lock or a rebase in flight into a refused
+	# turn over a tree nobody touched.
+	now="$(bash "$here/tree-snapshot.sh" "$tree" 2>/dev/null)" || return 0
+	[ -n "$now" ] || return 0
+	[ "$now" = "$line_digest" ] && return 0
+
+	# Whether the session routed is read exactly the way run-stats.sh reads it,
+	# from a copy of its `marker` and `lead` patterns and its `invokes_sluice`:
+	# a gate that disagreed with the meter would refuse turns the ledger
+	# reports as a run. The copy is kept in step with that file by hand.
+	#
+	# Lines are parsed one at a time and unparseable ones dropped, because the
+	# harness is still appending to this file while the hook reads it and the
+	# last line is regularly half written. Slurping would fail on that whole
+	# file and read a routed session as an unrouted one.
+	[ -f "$transcript" ] || return 0
+	jq -e -n -R '
+		def marker: "^[*_#>[:space:]]*(fast|main|deep)[[:space:]]+channel";
+		def lead: "^[^.!?\n]{0,100}[:=][[:space:]]*[*_]*(fast|main|deep)[[:space:]]+channel";
+		def texts: [ .message.content[]? | select(.type == "text") | .text ] | join("\n");
+		def invokes_sluice: [ .message.content[]?
+			| select(.type == "tool_use" and .name == "Skill")
+			| .input.skill? // empty ] | any(. == "sluice");
+		[ inputs | fromjson? // empty ]
+		| any(.[];
+			(.type == "assistant") and (((.isMeta == true) or (.isSidechain == true)) | not)
+			and ((texts | test(marker; "i") or test(lead; "i")) or invokes_sluice))
+	' "$transcript" >/dev/null 2>&1
+	case "$?" in
+		# 0 routed, 1 not. Anything else is jq failing rather than an answer
+		# about this session, and an unanswered question is not a refusal.
+		0) return 0 ;;
+		1) ;;
+		*) return 0 ;;
+	esac
+
+	mkdir -p "$root/nudged" 2>/dev/null || true
+	: >"$root/nudged/$sid" 2>/dev/null || true
+	jq -n '{
+		decision: "block",
+		reason: "sluice: this session has changed the tree since it opened and no channel was ever announced, so the work is running with none of the rules that its shape calls for and nothing to meter it from. Invoke the sluice skill now, route what you have been doing, and say which channel it is. If it genuinely changed nothing you own (a scratch file, or an edit that was not yours), say so and stop; this will not ask twice."
+	}'
+	return 1
+}
+
+if ! entry_nudge; then
+	exit 0
+fi
+
 [ -f "$STATUS" ] || exit 0
 
 # The session's own tree, and only that. status.sh lets a tree with no run of

package/skills/sluice/scripts/tree-snapshot.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Print one digest of where a git tree stands, for stop-guard.sh's entry check.
+#
+# Usage: tree-snapshot.sh <tree>
+# Exit 0 printed a digest, non-zero the tree could not be read. Prints nothing
+# on failure, and a caller that cannot read the tree has no comparison to make
+# rather than a change to report: an interrupted index, a lock held by another
+# git, or a rebase in flight are all "unknown", never "moved".
+#
+# It lives in its own file because two hooks compute it at two different moments
+# and a difference between their two copies would not read as a bug, it would
+# read as the tree having moved. That is the whole measurement.
+#
+# Three signals, because each covers a way of finishing work that the others
+# call standing still:
+#
+#   HEAD                        a session that committed leaves a clean tree
+#   diff HEAD                   a session that rewrote a file already modified
+#                               leaves the porcelain's shape untouched
+#   status --porcelain -uall    a session that filled an untracked directory
+#                               leaves one collapsed `?? build/` either way
+#
+# What it still misses, and why each is left:
+#
+#   - the content of a file that was already untracked when the session opened.
+#     Listing untracked paths is cheap and hashing their contents is not, and
+#     this runs at the end of every turn.
+#   - anything inside a nested repository. `status` does not descend into a
+#     directory carrying its own .git, so a session spent editing a scratch
+#     clone or a vendored checkout reads as a tree nobody touched.
+#   - who made the change. Nothing in a git tree records that, so a branch
+#     switch, a pull, or another session writing to the same tree all read as
+#     this session's work. stop-guard.sh bounds that rather than fixing it.
+
+set -uo pipefail
+
+tree="${1-}"
+[ -n "$tree" ] || exit 1
+command -v cksum >/dev/null 2>&1 || exit 1
+
+# `git diff HEAD` has no meaning before the first commit, and a repo without one
+# is a repo whose every file is untracked, which the porcelain covers. So an
+# unresolvable HEAD is carried as "no-head" rather than refused.
+#
+# It would be better to refuse when HEAD is unresolvable because the ref store
+# cannot be read, as opposed to because no commit exists yet, since the first is
+# a tree this script cannot describe. git gives no way to tell them apart:
+# `rev-parse --verify --quiet` exits 1 for both, and `for-each-ref` returns
+# empty for both, hiding an unreadable ref exactly as it reports an absent one.
+# Refusing on both would disarm the check permanently in any repo before its
+# first commit, which is an ordinary place to be writing code. Carrying both
+# costs a single nudge, and only in a tree whose refs broke partway through the
+# session it had already been read in.
+head="$(git -C "$tree" rev-parse --verify --quiet HEAD 2>/dev/null)" || head=""
+
+# Streamed into cksum rather than gathered into variables first. A diff is
+# unbounded, and this runs at the end of every turn until the session is either
+# routed or nudged: an 80MB file rewritten peaks at 334MB resident streamed,
+# against 622MB for a 61MB one held in a shell variable and then piped. What is
+# left is git loading the blobs, which is the price of reading content at all
+# and is the same for --numstat. Streaming also keeps NUL bytes intact, which a
+# command substitution silently drops, and dropping them would hide a change
+# confined to them.
+#
+# `exit 1` inside the group reaches the caller through pipefail, and the digest
+# cksum prints from a truncated read is discarded with it: a caller that cannot
+# read the tree needs no answer, and a short answer is a wrong one.
+digest="$( {
+	printf '%s\n' "${head:-no-head}"
+	git -C "$tree" status --porcelain -uall 2>/dev/null || exit 1
+	[ -n "$head" ] && { git -C "$tree" diff HEAD 2>/dev/null || exit 1; }
+	true
+} | cksum )" || exit 1
+
+printf '%s\n' "$digest"

package/skills/sluice/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "sluice",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "description": "Routes work by change shape into four channels (bypass, fast, main, deep) and applies only the rules each channel needs, so a one-line fix does not pay the cost of a multi-subsystem build. Carries seven rules as one-liners in the router and the full treatment in references read only on friction. Checks the finished plan with plan.sh validate rather than trusting it to memory, seeds the run state from it, keeps a deep run's task breakdown in .sluice/run.json so a statusline segment, one status command and a SessionStart hook can answer where the run is (the hook prints a live run at every session start, compaction included), and closes each run with a ledger read out of the session transcript: elapsed, tools, tokens, and what each dispatched agent cost where the transcript recorded it. Claude Code only; stands down where the superpowers pipeline governs the repo.",
   "author": "iceinvein",
   "type": "prompt",