crewforth 0.0.1 → 3.0.0-rc.1

package/kit/hooks/route-hint.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# Route hint — name the owning agent next to the request itself.
+#
+# WHY THIS EXISTS, measured rather than assumed. Crewforth's premise is that specialist agents run the work. On a
+# focused, single-domain request that does not happen: 42 measured sessions across the eval suite, two A/B pairs
+# and a twelve-agent domain sweep produced ZERO spontaneous delegations. Two things were tried first and both
+# came back zero — rewriting the agents' `description` into ownership language, and telling the discipline to
+# call the Agent tool concretely. What DOES work is naming the agent explicitly: a command body that @-mentions
+# its agents delegated 3 of 3, and a single request carrying twelve different jobs fanned out to all twelve
+# owners correctly. So the mechanism is sound; the trigger is the shape of the request.
+#
+# The subagents docs list three inputs to the delegation decision: "the task description in your request, the
+# `description` field in subagent configurations, and current context". Crewforth had touched the second and the
+# third. This hook is the first: `UserPromptSubmit` can return `additionalContext`, and for that event the docs
+# place it "alongside the submitted prompt" — the one position we had never used.
+#
+# It states an owner. It never decides FOR the model, never blocks, and stays silent unless a match is clear:
+# a wrong route is worse than none, because it looks like Crewforth worked.
+#
+# ---------------------------------------------------------------------------------------------------------
+# ONE AWK PASS, NOT A SHELL LOOP — this hook runs on EVERY prompt, so its cost is the session's floor.
+#
+# The first version scored the components with nested shell loops: for each of ~50 component files a
+# grep+head+grep+sed, and then for each of its trigger phrases a `norm()` pipeline (sed|tr|sed) plus a
+# `printf|grep -qE` with another `sed` nested inside the pattern. 348 phrases across the shipped payload put
+# that at roughly 2000 process spawns per prompt. Measured on an M-series Mac: 3.35s of pure fork overhead
+# (104% CPU, ~1.7ms per spawn) for a hook whose actual work is substring matching on a few KB of text.
+#
+# That is merely wasteful on macOS/Linux. On Windows it is fatal. Git Bash has no real fork(): every process
+# is a CreateProcess plus the MSYS2 emulation layer plus whatever the AV scanner charges. Measured on a
+# Windows 11 desktop rather than assumed: 62-135 ms per spawn idle, and up to ~400 ms while the machine is
+# busy — forty to eighty times the ~1.7 ms Linux pays, not the "20-50 ms" this comment claimed before anyone
+# ran it here. The same 2000 spawns therefore land at two to four MINUTES, not 40-100 seconds, against a
+# 10s hook timeout. Claude Code blocks on the hook until that timeout expires, on EVERY prompt, and then
+# discards the output — so Crewforth paid the full stall and got no routing for it. That is the "it hangs and
+# nothing works" report from Windows users, and it is not a Claude Code bug: Crewforth was spending the budget.
+#
+# Everything below is therefore one awk invocation over the component files, with the normalisation and the
+# matching done inside awk. Total external processes: FIVE — cat, sed, sed, head, awk. (The count said four
+# until it was traced with `bash -x` on Windows; the `cat` on the next line reads stdin and had been read
+# past.) Measured end to end here: 5 spawns, ~328 ms per prompt idle. eval/smoke-test.sh §7y pins the shape.
+set -uo pipefail
+IN="$(cat)"
+case "$IN" in *'"hook_event_name"'*UserPromptSubmit*) ;; *) exit 0 ;; esac
+
+# Two editions, two layouts: a full install puts the components under .claude/, the plugin ships them beside the
+# hook itself. Resolve both or the plugin channel silently loses routing — the same one-channel-weaker failure
+# the commit content gate had before 1.9.0.
+#
+# `${VAR//\\//}` folds backslashes to forward slashes. On Windows both CLAUDE_PROJECT_DIR and CLAUDE_PLUGIN_ROOT
+# arrive as native paths (`C:\Repos\app`), and a native path pasted into a POSIX one produces
+# `C:\Repos\app/.claude/agents` — a shape neither side reliably resolves. Forward slashes work on every
+# platform, including Git Bash, and the substitution is a no-op where there is nothing to fold.
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  PROOT="${CLAUDE_PLUGIN_ROOT//\\//}"
+  [ -d "$PROOT/agents" ] && { AGENTS="$PROOT/agents"; SKILLS="$PROOT/skills"; }
+fi
+if [ -z "${AGENTS:-}" ]; then
+  PROJ="${CLAUDE_PROJECT_DIR:-.}"; PROJ="${PROJ//\\//}"
+  AGENTS="$PROJ/.claude/agents"; SKILLS="$PROJ/.claude/skills"
+fi
+[ -d "$AGENTS" ] || [ -d "$SKILLS" ] || exit 0
+
+# The prompt text, taken as a raw slice: no jq dependency, and a partial read is fine because matching is by
+# substring anyway. Everything after `"prompt":"` up to the closing quote that is not escaped. It goes to awk
+# through the ENVIRONMENT, never through `-v`: awk expands escape sequences in a `-v` value, so a prompt
+# containing a literal backslash would be rewritten before the normaliser ever saw it.
+# TWO FIELD NAMES, because the payload has carried both and this hook is the only thing in Crewforth that reads
+# the prompt text at all. The published UserPromptSubmit schema names the field `user_input`; the payload this
+# hook was written against, and the suite that pins it, used `prompt`. Which one a given CLI sends is not a fact
+# this repo can establish from here, and getting it wrong is SILENT: the slice comes back empty, the hook exits
+# 0, and routing is simply gone while every test stays green because the tests choose the name too. So both are
+# accepted. The fallback costs nothing on the path that already worked — it only runs when the first name found
+# nothing. `prompt_id` cannot be mistaken for `prompt`: the pattern includes the closing quote.
+CREW_PROMPT="$(printf '%s' "$IN" | sed -n 's/.*"prompt"[[:space:]]*:[[:space:]]*"\(.*\)/\1/p' | sed 's/","[a-z_]*":.*$//' | head -c 4000)"
+[ -n "$CREW_PROMPT" ] || CREW_PROMPT="$(printf '%s' "$IN" | sed -n 's/.*"user_input"[[:space:]]*:[[:space:]]*"\(.*\)/\1/p' | sed 's/","[a-z_]*":.*$//' | head -c 4000)"
+[ -n "$CREW_PROMPT" ] || exit 0
+
+# NOT EVERY TURN CARRIES A REQUEST. A field session watched this hook inject "Use the <x> subagent for this task"
+# on turns where the user had typed nothing at all: a background subagent finished, its REPORT arrived as the
+# turn's text, and the report was scored as if it were the request. Both times the named owner was the agent
+# whose finished work was being reported -- so the hint pushed the main thread to re-delegate work that was
+# already done, at the 10-16k tokens a subagent floor costs. Ten injections that session, zero of them useful.
+#
+# Whether Claude Code really raises UserPromptSubmit for those turns is NOT established here, and this does not
+# depend on the answer: text that OPENS with a notification marker is not a user request under any reading, so
+# staying quiet is right either way. Anchored to the start deliberately -- a person may well write the words
+# "system notification" inside a genuine request, and only a notification BEGINS as one.
+case "$CREW_PROMPT" in
+  '<task-notification'*|'<system-reminder'*|'<cross-session-message'*|'<local-command-stdout'*\
+  |'[SYSTEM NOTIFICATION'*|'[Task '*|'Another Claude session sent a message'*)
+    exit 0 ;;
+esac
+export CREW_PROMPT
+
+# Glob expansion is a shell builtin — no forks. Agents FIRST, then skills: awk reads its arguments in order and
+# the tie-break below is first-wins, so the order is part of the contract, not incidental.
+FILES=()
+for f in "$AGENTS"/*.md "$SKILLS"/*/SKILL.md; do [ -e "$f" ] && FILES+=("$f"); done
+[ "${#FILES[@]}" -gt 0 ] || exit 0
+
+# Score every installed agent by how many of its trigger phrases appear. Longest phrase wins ties: "state
+# management" is a stronger signal than "state", and a two-word hit beats a one-word hit from another agent.
+# Agents AND skills are scored. The agent answers "who owns this"; the skill answers "how is it done", and the
+# skill is the cheaper, more useful nudge: a subagent re-pays its whole context (measured at 10-16k tokens for a
+# no-op), while a skill just loads its method into the turn already in progress. Measured on a focused request,
+# neither fired on its own — 12 domain tasks produced zero delegations and a skill in only 2 of 12 — so the
+# method Crewforth exists to carry was simply absent from the work.
+RES="$(awk '
+# Same normalisation the routing eval uses: Turkish diacritics folded, lowercased, every run of non-alphanumerics
+# collapsed to one space, and the whole string space-padded so a match is word-bounded. Without the padding a
+# short trigger hides inside a longer word — `UI` inside `build` once sent CI failures to the frontend expert.
+# Folding runs before tolower() because tolower() is ASCII-only in a byte-oriented awk; the gsub pairs cover
+# both cases explicitly so the result does not depend on which awk Git Bash happens to ship.
+function norm(s) {
+  gsub(/Ç/,"c",s); gsub(/ç/,"c",s); gsub(/Ğ/,"g",s); gsub(/ğ/,"g",s)
+  gsub(/İ/,"i",s); gsub(/ı/,"i",s); gsub(/Ö/,"o",s); gsub(/ö/,"o",s)
+  gsub(/Ş/,"s",s); gsub(/ş/,"s",s); gsub(/Ü/,"u",s); gsub(/ü/,"u",s)
+  s = tolower(s)
+  gsub(/[^a-z0-9]+/," ",s)          # also sweeps up any multi-byte leftovers, one space per run
+  sub(/^ +/,"",s); sub(/ +$/,"",s)
+  return s
+}
+BEGIN { np = " " norm(ENVIRON["CREW_PROMPT"]) " "; bestA=0; bestS=0; nameA=""; nameS="" }
+seen[FILENAME] { next }                                    # one Trigger-phrases line per component, the first
+{
+  if (tolower($0) !~ /trigger phrases:/) next
+  seen[FILENAME] = 1
+  if (FILENAME ~ /\/SKILL\.md$/) { kind="skill"; name=FILENAME; sub(/\/SKILL\.md$/,"",name) }
+  else                          { kind="agent"; name=FILENAME; sub(/\.md$/,"",name) }
+  sub(/.*\//,"",name)
+  score = 0; rest = $0
+  while (match(rest, /"[^"]+"/)) {
+    ph   = substr(rest, RSTART+1, RLENGTH-2)
+    rest = substr(rest, RSTART+RLENGTH)
+    p = norm(ph)
+    if (p == "") continue
+    # Suffix-tolerant, prefix-anchored: the trigger must START at a word boundary, but may carry up to three
+    # trailing letters. Word-bounded matching alone silently lost every inflection — `component` did not match
+    # "components", `test` did not match "tests" — which is how a hook that looked correct stayed quiet on two
+    # thirds of real prompts. The boundary that matters is the LEADING one: it is what keeps `ui` out of `build`.
+    # Written as three optional letters rather than {0,3} because interval expressions are not universal in awk.
+    # No escaping needed: norm() has already reduced the phrase to [a-z0-9 ], so it carries no metacharacter.
+    if (np ~ ("(^| )" p "[a-z]?[a-z]?[a-z]?( |$)")) score += length(ph)
+  }
+  if (score <= 0) next
+  # An AGENT outranks a SKILL when both match: agent = who, skill = how, and the agent applies its own skills
+  # anyway, so naming it delivers the method PLUS the isolation and the audit path. A skill is named when no
+  # agent owns the domain at all (iterate, reflect, worktree, eval-grader).
+  #
+  # THE TWO KINDS ARE SCORED SEPARATELY, and that is the fix for a measured silence. The preference used to be
+  # applied by OVERWRITING the best match the moment any agent matched, whatever its score — so a one-word
+  # agent hit discarded a far stronger skill hit, and the discarded total then fell under the floor below and
+  # the hook printed NOTHING. Measured before this change: "this needs an accessibility audit" produced the
+  # a11y hint, and "the PAGE needs an accessibility audit" produced silence, because `page` is a
+  # crew-frontend-expert trigger worth 4 which replaced the a11y score of ~30 and then failed `>= 6`. Adding a common noun
+  # to a request removed the routing entirely, which is the opposite of what a preference is for. Each kind now
+  # keeps its own best and the preference is applied at the END, among candidates that clear the floor.
+  if (kind == "agent") { if (score > bestA) { bestA=score; nameA=name } }
+  else                 { if (score > bestS) { bestS=score; nameS=name } }
+}
+# Silence is the default. No match, or a match too weak to be sure, means the main thread decides as before.
+# The agent is preferred only when it is credible on its own: a weak agent match no longer buries a strong skill.
+END {
+  if      (bestA >= 6) print "agent\t" nameA
+  else if (bestS >= 6) print "skill\t" nameS
+}
+' "${FILES[@]}" 2>/dev/null)"
+
+[ -n "$RES" ] || exit 0
+BESTKIND="${RES%%	*}"; BEST="${RES#*	}"
+[ -n "$BEST" ] && [ "$BEST" != "$RES" ] || exit 0
+
+# The wording is an INSTRUCTION, not a suggestion, and that distinction is the whole experiment. The first
+# version hedged — "unless it is a one-line edit", "if it is genuinely not that agent's work, say so" — which
+# handed the model two explicit ways to decline, and it took them: 4 of 12. The docs give the phrasing that
+# works verbatim ("Use the test-runner subagent to fix failing tests"), so that is what goes in. A user typing
+# "use crew-frontend-expert for this" gets obeyed without argument; there is no reason to write it more weakly
+# just because a hook is doing the typing.
+if [ "$BESTKIND" = skill ]; then
+  MSG="Use the \`$BEST\` skill for this task."
+else
+  MSG="Use the $BEST subagent for this task."
+fi
+printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$MSG"

package/kit/hooks/secret-blocklist.txt

@@ -0,0 +1,82 @@
+# Secret scanner — high-signal patterns (ERE, case-SENSITIVE). One regex per line; '#' starts a comment.
+# These match secret VALUES (keys / tokens / private keys), not the word "secret".
+# False positive on a real (test) value? Add the EXACT pattern line to .secret-allowlist.txt at the repo root,
+# or replace the value with a placeholder. Deliberate bypass: git commit --no-verify (explicit request only, §4.5).
+#
+# Each pattern carries its own case, on the line right below it:
+#   #test:       a sample this pattern MUST catch
+#   #test-clean: a sample no pattern may catch
+# smoke-test.sh discovers them and drives the REAL hook with them, and it FAILS if a pattern has no case at
+# all — an untested regex is how a typo ships as a gate that silently matches nothing. Samples are deliberately
+# written with a {{A<n>}} placeholder that the test harness expands to n 'A's at run time. The file therefore
+# never contains a contiguous secret-shaped literal — which matters because it ships into every project's
+# .claude/, where their scanners would flag it, and because GitHub push protection blocks such a literal on
+# sight regardless of how low its entropy is (measured: it rejected the Stripe sample).
+
+# PEM private keys (RSA / EC / OPENSSH / DSA / PGP ...)
+-----BEGIN ([A-Z]+ )?PRIVATE KEY-----
+#test: -----BEGIN RSA PRIVATE KEY-----
+#test: -----BEGIN PRIVATE KEY-----
+
+# AWS access key id
+(AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|A3T)[A-Z0-9]{16}
+#test: aws_access_key_id = AKI{{A17}}
+
+# GitHub tokens (personal / oauth / user / server / refresh) + fine-grained PAT
+gh[pousr]_[A-Za-z0-9]{36,}
+#test: token: ghp_{{A36}}
+github_pat_[A-Za-z0-9_]{22,}
+#test: token: github_pat_{{A24}}
+
+# Google API key
+AIza[A-Za-z0-9_-]{35}
+#test: key=AIza{{A35}}
+
+# Slack token
+xox[baprs]-[A-Za-z0-9-]{10,}
+#test: SLACK_TOKEN=xoxb-{{A12}}
+
+# Stripe live secret / restricted key
+(sk|rk)_live_[A-Za-z0-9]{20,}
+#test: STRIPE=sk_live_{{A24}}
+
+# OpenAI / Anthropic API keys
+sk-(ant-|proj-)?[A-Za-z0-9_-]{24,}
+#test: API_KEY=sk-ant-{{A24}}
+
+# npm access token
+npm_[A-Za-z0-9]{36}
+#test: //registry.npmjs.org/:_authToken=npm_{{A36}}
+
+# SendGrid API key
+SG\.[A-Za-z0-9_-]{16,32}\.[A-Za-z0-9_-]{16,}
+#test: SENDGRID_API_KEY=SG.{{A16}}.{{A20}}
+
+# JSON Web Token (header.payload.signature)
+eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{10,}
+#test: Authorization: Bearer eyJAAAAAAAAAA.eyJAAAAAA.AAAAAAAAAA
+
+# A credential carried in a URL query. THE CLASS EVERY PATTERN ABOVE STRUCTURALLY CANNOT SEE: all eleven
+# recognise a credential by its own SHAPE -- AKIA, ghp_, AIza, xox, sk_live_, sk-ant-, npm_, SG., a JWT, a PEM
+# header -- and a token with no issuer prefix has no shape to recognise. Measured on a published install with
+# the real hook: `http://127.0.0.1:7911/?token=<uuid>`, a bare uuid, and `token=` plus 32 hex all committed
+# cleanly while the calibration lines beside them were caught, so this was a hole rather than a guess.
+# Crewforth produces exactly such a URL itself -- the Studio panel mints one per run and the command hands it to
+# the user -- but the pattern is deliberately about the QUERY KEY, not about that panel: any `?token=` long
+# enough to be real is one, whoever minted it.
+# Anchored on the key and a 20-character floor so the ordinary ways of WRITING one about stay committable:
+# `?token=<your-token>` and `?token=$VAR` carry characters the class excludes, so the run measures zero.
+[?&](token|api_?key|apikey|access_token|auth_token)=[A-Za-z0-9._~-]{20,}
+#test: curl https://api.example.com/v1/items?token={{A20}}
+#test: https://127.0.0.1:7777/?token={{A32}}
+#
+# The other half of the same leak is NOT closable here and is left to `.private-terms.txt` on purpose: a machine
+# name is any word, so no pattern can tell one from prose. That half stays model discipline, and /crew-studio
+# says so where it tells the model what may be quoted.
+
+# Values that LOOK secret-adjacent but are not, and must stay committable.
+#test-clean: open http://127.0.0.1:7777/?token=<your-token-here>
+#test-clean: the panel URL carries ?token=$STUDIO_TOKEN from the environment
+#test-clean: const apiKey = process.env.STRIPE_SECRET_KEY
+#test-clean: # set GITHUB_TOKEN in the CI environment, never in the repo
+#test-clean: private key handling is documented in docs/security.md

package/kit/hooks/session-guard.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# Stop hook — when session fill crosses a threshold it GUARANTEES the handoff recommendation reaches the USER.
+# Session management = a gate at the threshold, not a wish. But the gate must not nag or burn tokens:
+#   - It surfaces the recommendation as a neutral `systemMessage` (user-facing warning), NOT a hook error.
+#     (Claude Code renders a BLOCKING Stop hook — exit 2 — as "Stop hook error: ...". We deliberately never block.)
+#   - It fires ONCE PER THRESHOLD per session: once at 75% (warn), once more at 90% (critical). Never every turn,
+#     so it never forces an extra assistant continuation — which would burn tokens and fill the context faster,
+#     i.e. the gate would cause the very thing it exists to prevent.
+#   - It NEVER blocks the stop: every path exits 0. A measurement failure fails open, silently.
+# context-usage.sh does the measurement. No automatic /clear — approval is the user's (§4.4).
+# The model is nudged separately every turn by context-usage.sh (UserPromptSubmit); this hook is the
+# guaranteed USER-facing alert. A new session (or /clear) mints a new session_id and re-arms both thresholds.
+set -uo pipefail
+HERE="$(cd "$(dirname "$0")" && pwd)"
+IN="$(cat 2>/dev/null || true)"
+
+# Loop guard: if this Stop is already a Stop-hook continuation, do nothing (defensive; we never block anyway).
+case "$IN" in
+  *'"stop_hook_active":true'*|*'"stop_hook_active": true'*) exit 0 ;;
+esac
+
+# Per-session dedup key: session_id from the Stop stdin JSON (documented field), else the transcript
+# filename. Sanitized to a safe filename fragment. Without any key we fall back to a shared marker
+# (that degenerate case coincides with a measurement failure, which exits silently below anyway).
+#
+# Pure parameter expansion, not `sed | head | tr`. This hook runs on EVERY Stop — once per turn — and on Git
+# Bash a process costs 60-135 ms (measured on a Windows 11 desktop: this hook was 22 processes and 1,805 ms
+# per turn end, of which these three lines were 8). Extraction is shortest-match `#*`, so it takes the FIRST
+# occurrence of the key exactly as the sed did; the `[!…]` class strips to the same safe filename fragment
+# `tr -cd` produced, and that form works on the bash 3.2 macOS ships.
+_slice(){ # $1 = payload, $2 = key -> the value up to the next unescaped-quote-free boundary, "" if absent
+  local r="${1#*\"$2\"}"
+  [ "$r" != "$1" ] || return 0
+  r="${r#*\"}"                      # past `: "` to the value's opening quote
+  printf '%s' "${r%%\"*}"
+}
+TP="$(_slice "$IN" transcript_path)"
+# The path arrives JSON-encoded, so on Windows it carries doubled backslashes. Git Bash happens to accept
+# `C:\\Users\\…` (Windows collapses repeated separators), which is why this was never noticed here — but
+# context-usage.sh already normalises for the same field and does not rely on that, and a check that depends
+# on one shell's tolerance is a check that stops running when someone uses another. Free: no process.
+TP="${TP//\\\\//}"; TP="${TP//\\//}"
+KEY="$(_slice "$IN" session_id)"; KEY="${KEY//[!A-Za-z0-9._-]/}"
+if [ -z "$KEY" ]; then KEY="${TP##*[/\\]}"; KEY="${KEY//[!A-Za-z0-9._-]/}"; fi
+[ -n "$KEY" ] || KEY="unknown"
+
+# Compaction generation. A `/compact` does NOT mint a new session_id — only a new session or `/clear` does —
+# so the per-tier markers below survive it, and that silently disarms this gate exactly where it matters most:
+# a session warned at 90% compacts down to ~5%, climbs all the way back, and the user is never told a second
+# time. Keying the markers by compaction COUNT gives every generation its own pair of thresholds.
+# The boundary record is `"subtype":"compact_boundary"` with `compactMetadata.trigger` (verified against real
+# transcripts). grep, not awk: this runs inside a hook timeout on every Stop, and the same size guard
+# context-usage.sh uses applies — past the cap we skip the count and fall back to the old single-generation
+# behaviour rather than risk the timeout.
+COMP=0; AUTOC=0
+if [ -n "$TP" ] && [ -f "$TP" ]; then
+  # `$(( ))` instead of `| tr -cd '0-9'`: arithmetic already ignores the surrounding whitespace wc and grep
+  # emit, and it costs no process where tr costs one each — three of them, on every turn.
+  #
+  # NO `|| echo 0` on the greps. `grep -c` with zero matches PRINTS "0" AND EXITS 1, so the fallback
+  # fired too and the value became two lines — `0\n0` — which `$(( ))` cannot parse. Measured on a real
+  # session: "session-guard.sh: line 61: 0\n0 + 0 : arithmetic syntax error". Every transcript that has
+  # not been compacted takes that path, which is every fresh session, so the 75/90 warning this hook
+  # exists to emit was failing before it could speak. `wc -c` keeps its fallback: it prints nothing when
+  # the file cannot be read, so there the `||` supplies a value rather than appending a second one.
+  SZ="$(wc -c < "$TP" 2>/dev/null || echo 0)"; SZ=$(( ${SZ:-0} + 0 ))
+  if [ "$SZ" -le "${CREW_CONTEXT_MAX_BYTES:-209715200}" ]; then
+    COMP="$(grep -c '"subtype": *"compact_boundary"' "$TP" 2>/dev/null)";  COMP=$(( ${COMP:-0} + 0 ))
+    AUTOC="$(grep -c '"compact_boundary".*"trigger": *"auto"' "$TP" 2>/dev/null)"; AUTOC=$(( ${AUTOC:-0} + 0 ))
+  fi
+fi
+marker(){ printf '%s/crew-session-guard.%s.c%s.%s' "${TMPDIR:-/tmp}" "$KEY" "$COMP" "$1"; }
+
+# An AUTO compaction is not a milestone, it is a loss: state nobody chose to drop is already gone, and the fill
+# reading right after it is reassuringly low precisely because the context was thrown away. Announce it once per
+# generation, independently of the fill tier — waiting for 75% would report the loss long after it happened.
+if [ "${AUTOC:-0}" -gt 0 ] && [ ! -e "$(marker autocompact)" ]; then
+  : > "$(marker autocompact)" 2>/dev/null || true
+  printf '{"systemMessage":"⚠️ Auto-compaction has fired %s time(s) this session — context was dropped that nobody chose to drop. Check that docs/SESSION_STATE.md still matches reality, and hand off at the next phase boundary instead of riding the fill up to another one."}\n' "$AUTOC"
+  exit 0
+fi
+
+# Real context%, from context-usage.sh's measurement. Fail-open on any error.
+#
+# FAST PATH — read the figure context-usage.sh already published this turn. That hook runs on UserPromptSubmit,
+# measures exactly this, and now writes it to a session-keyed file. Re-deriving it here meant a second shell
+# startup plus a second full transcript scan at the end of EVERY turn: measured at ~31 processes per Stop, and
+# on a corporate Windows machine a process costs ~290ms, so the turn ended with seconds of silence.
+#
+# Read with `$(<file)` — a builtin, no `cat`. Parsed by word splitting, no `sed`. What it costs: the reading is
+# from the start of the turn, so it excludes this turn's own output and can cross a threshold one turn late.
+# For a warning that never blocks, one turn of lag is worth seconds a turn, and it is not silent: without the
+# file we measure properly below, so the accurate path is always there when the fast one is not.
+PCT=""; TOTAL=""; WINDOW=""; LEVEL=""; LINE=""
+CACHE="${TMPDIR:-/tmp}/crew-context.${KEY}"
+if [ -f "$CACHE" ]; then
+  read -r PCT TOTAL WINDOW LEVEL < "$CACHE" 2>/dev/null || true
+  case "$PCT" in ''|*[!0-9.]*) PCT="" ;; esac      # anything unexpected -> fall through and measure
+  [ -n "$PCT" ] && LINE="🔋 Session: %$PCT ($TOTAL/$WINDOW token) → $LEVEL"
+fi
+
+if [ -z "$PCT" ]; then
+  # SLOW PATH — no published reading (first turn, a by-hand run, or context-usage silent). Measure for real.
+  # --verbose here: this line reaches the USER at most twice per session, so the raw token counts are free.
+  LINE="$(printf '%s' "$IN" | bash "$HERE/context-usage.sh" --verbose 2>/dev/null || true)"
+  LINE="${LINE%%$'\n'*}"                     # first line, without paying `head` a process for it
+  [ -n "$LINE" ] || exit 0
+  # Pull the percentage back out of the "🔋 Session: %77.2 (...)" line. context-usage.sh pins LC_ALL=C, so the
+  # decimal separator is always '.' whatever the locale. No number -> cannot classify -> stay silent (fail open).
+  # Pure expansion rather than `sed | head`: take everything after the first '%', then stop at the first
+  # character that is not a digit or a dot. Same first-match semantics as the sed, two processes cheaper, and
+  # this runs at the end of every turn.
+  PCT="${LINE#*%}"
+  [ "$PCT" != "$LINE" ] || PCT=""
+  PCT="${PCT%%[!0-9.]*}"
+  case "$PCT" in ''|*[!0-9.]*|.*) PCT="" ;; esac
+  [ -n "$PCT" ] || exit 0
+fi
+
+# Highest threshold crossed. Compared under LC_ALL=C so '77.2' parses identically everywhere.
+# Compared on the integer part with shell arithmetic rather than two `awk` calls. Two spawns at the end of every
+# turn bought nothing here: the thresholds are whole numbers, so truncating is exactly equivalent — 89.9 is below
+# 90 either way — and dropping the decimal also drops the locale hazard the awk calls existed to pin down.
+INT="${PCT%%.*}"; INT="${INT:-0}"
+case "$INT" in ''|*[!0-9]*) exit 0 ;; esac
+TIER=""
+[ "$INT" -ge 90 ] && TIER=90
+[ -n "$TIER" ] || { [ "$INT" -ge 75 ] && TIER=75; }
+[ -n "$TIER" ] || exit 0
+
+# Already warned at this tier this session? Stay silent — one alert per threshold, not one per turn.
+[ -e "$(marker "$TIER")" ] && exit 0
+# Stamp this tier AND every lower one: jumping 60 -> 92 in a single turn must not let the 75 warning fire
+# later (e.g. once /compact drops the fill back under 90).
+for t in 75 90; do
+  [ "$t" -le "$TIER" ] && { : > "$(marker "$t")" 2>/dev/null || true; }
+done
+
+if [ "$TIER" = 90 ]; then
+  MSG="CRITICAL >90% — hand off NOW: apply the handoff skill, write docs/SESSION_STATE.md, then /clear. Auto-compaction is close and it will cost you the handover."
+else
+  MSG=">75% threshold. Recommended: apply the handoff skill, write docs/SESSION_STATE.md, then /clear. Manual; your call."
+fi
+
+# JSON-escape backslash + double-quote in the measured line before embedding it.
+SAFE="$(printf '%s' "$LINE" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+# exit 0 + systemMessage: a neutral, user-facing warning (NOT a hook error, does NOT force an extra turn).
+printf '{"systemMessage":"%s | %s"}\n' "$SAFE" "$MSG"
+exit 0

package/kit/hooks/session-rehydrate.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# SessionStart hook — after a context boundary (compact / clear / resume), point the model back at the handover
+# so in-progress work survives the boundary. This closes Crewforth's handoff loop: `handoff` writes
+# docs/SESSION_STATE.md → the user runs /clear (or context auto-compacts) → a fresh context starts → THIS hook
+# re-surfaces the file so the next turn resumes from it instead of from zero.
+#
+# Deliberate scope (honest, spec-grounded):
+#   - SessionStart is the right event: its stdout / hookSpecificOutput.additionalContext is injected into the
+#     model's context (docs: "Re-inject context after compaction"). PreCompact is NOT used — it can only block
+#     compaction, not add instructions to the summary, and blocking is not what we want.
+#   - Matched on compact|clear|resume, NOT startup: those three are explicit "continue where I left off" boundaries.
+#     startup fires on every unrelated session open and would keep surfacing a stale handover — that would nag.
+#   - CLAUDE.md itself reloads on /compact and /clear on its own, so this hook does NOT re-inject the discipline —
+#     only the session-specific state the reload can't recover.
+#   - Fails OPEN and SILENT: no handover file, no output. It never blocks the session (always exits 0).
+set -uo pipefail
+IN="$(cat 2>/dev/null || true)"
+
+# Project root: CLAUDE_PROJECT_DIR (set for hooks) → cwd from the stdin JSON → PWD.
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$ROOT" ]; then
+  ROOT="$(printf '%s' "$IN" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+fi
+[ -n "$ROOT" ] || ROOT="$PWD"
+# Windows hands both CLAUDE_PROJECT_DIR and the stdin `cwd` over as native paths (`C:\Repos\app`), and the stdin
+# one arrives JSON-ENCODED on top of that — `C:\\Repos\\app`. Slicing it out with sed keeps the doubled
+# backslashes, so ROOT pointed at a directory that cannot exist and the hook silently rehydrated nothing.
+# Undo the JSON escaping first (`\\`), then fold any lone separator. Both are no-ops on a POSIX path.
+ROOT="${ROOT//\\\\//}"; ROOT="${ROOT//\\//}"
+
+STATE="$ROOT/docs/SESSION_STATE.md"
+[ -s "$STATE" ] || exit 0   # no (non-empty) handover → nothing to rehydrate, stay silent
+
+MSG="A session handover from before this context boundary exists at docs/SESSION_STATE.md. If the user's request continues that work, read it first — it holds the in-progress task state, open decisions, and the intended next step — and do not restart from scratch. If the request is about something else, do not bring it up."
+
+# hookSpecificOutput.additionalContext is the documented channel that injects text into the model's context.
+# ONE PATH, no jq: MSG is a fixed constant with no quote, backslash, control character or newline, so it needs no
+# escaping and every machine emits the same bytes. If you ever make MSG dynamic, escape it the way board-sync.sh
+# does (jq-identical, measured) — a raw quote or tab here makes JSON the CLI silently drops.
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$MSG"
+exit 0