crewforth 3.3.0 → 3.4.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ Crewforth was named Claude Starter Kit until 3.0.0.
 Notable changes to this project are recorded here. Format follows [Keep a Changelog](https://keepachangelog.com/en/),
 versioning follows [SemVer](https://semver.org/).
 
+## [3.4.0] — 2026-10-30
+
+### Added
+
+- **An anonymous install count.** After a successful `npx crewforth init`, Crewforth sends one request, once per
+  project: `GET https://ping.crewforth.com/install?v=<version>`, the version and nothing else, after printing a line that says so. No
+  ID, path, project, host or user name is sent, and `adopt`, `update`, `add`, `studio`, the hooks and the plugin send
+  nothing. `CREW_NO_TELEMETRY` or `DO_NOT_TRACK` set to anything but `0` turns it off, and nothing is sent where `CI`
+  is set. The request gets 1.5 seconds and a failure never changes the install. The endpoint is a Cloudflare Worker
+  whose source is in the repository and which keeps a count per day and version, nothing else. README → Telemetry.
+- **The site says which release it describes.** The home page shows the version above its heading, and every page
+  shows it next to the logo, each linked to the changelog in the page's language. The number is read from `VERSION`
+  when the site is built, so a release renames it without anyone editing a page, and a `VERSION` that is not a
+  version fails the build.
+- **A guessed fill figure is reported.** The 🔋 figure in a reply is meant to be copied from the hook's measured
+  line, and nothing checked that it was. When the measured line stopped arriving, a session went on printing a fill
+  that rose from 45% to 86% while its transcript measured about 30%, and the user handed the session off on that
+  number. The Stop hook now measures the fill itself, and when the reply's figure is more than 5 points away it
+  tells the user both numbers. `CREW_FILL_TOLERANCE` changes the margin.
+
+### Fixed
+
+- **A session resumed in a worktree keeps its gates.** `.claude/` is gitignored, so a worktree made with
+  `git worktree add ../x` has none. A session that entered one kept its hooks only until it was resumed; from then
+  on Claude Code read the worktree's settings, found none, and ran no Crewforth hook at all: no commit approval, no
+  write gate, no fill reading. A new hook copies this checkout's `.claude/` into such a worktree when a session
+  enters it, without `worktrees/`, `state/`, the review record and the gate log, and refuses the move when the copy
+  cannot be made. Worktrees Claude Code creates under `.claude/worktrees/` were not affected and are left alone. The
+  plugin edition does not need it: its hooks load in a repository's worktrees too.
+
 ## [3.3.0] — 2026-10-29
 
 ### Added

package/README.md

@@ -41,6 +41,10 @@ Then open Claude Code and run `/crew-doctor` to confirm the setup. Requires bash
 
 When a new version is published, Claude asks once at the start of a session whether to update; it never updates on its own. Run `/crew-update` inside a session, or `npx crewforth@latest update`.
 
+## Telemetry
+
+After a successful `npx crewforth init`, Crewforth sends one anonymous count, once per project: `GET https://ping.crewforth.com/install?v=<version>`, the version and nothing else, after printing a line that says so. No ID, path, project, host or user name is sent; `adopt`, `update`, `add` and `studio` send nothing. Turn it off with `CREW_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`; nothing is sent where `CI` is set. Details: [README → Telemetry](https://github.com/Crewforth/crewforth#telemetry).
+
 ## Links
 
 Documentation: [crewforth.com](https://crewforth.com) · Source and issues: [github.com/Crewforth/crewforth](https://github.com/Crewforth/crewforth) · Licence: MIT

package/VERSION

@@ -1 +1 @@
-3.3.0
+3.4.0

package/bin/cli.js

@@ -496,3 +496,58 @@ try {
 } finally {
   try { fs.rmSync(stage, { recursive: true, force: true }); } catch (_) { /* best effort */ }
 }
+
+// ================================ install count ================================
+// One anonymous "an install finished" count, so the project can tell how many installs actually happen (npm's
+// download figure also counts mirrors, CI and bots). The single definition of what is sent, when, and how it is
+// turned off; README → Telemetry describes it, and nothing else in the package sends anything.
+//   when:  a successful init (start.sh exit 0) only — never adopt/update/add/studio, a hook or a session;
+//          once per project: the marker lives in the git directory (or .claude/ outside git) and is never sent.
+//   what:  GET <endpoint>/install?v=<version>, User-Agent "crewforth", no body. No ID of any kind, no path, no
+//          project or user name, no host, no language, no OS, no time (the server keeps its own clock).
+//   off:   CREW_NO_TELEMETRY or DO_NOT_TRACK set to anything but 0, or CI defined at all. Off means nothing is
+//          printed, sent or written.
+//   cost:  the request is given 1.5 s and every failure is swallowed: it never changes the exit code or prints
+//          an error. The notice line is printed BEFORE the request.
+// The endpoint is a Cloudflare Worker whose source is packaging/install-ping-worker/, served at ping.crewforth.com.
+// An empty constant sends and prints nothing. CREW_TELEMETRY_URL replaces it for the tests only.
+const INSTALL_COUNT_URL = 'https://ping.crewforth.com';
+const INSTALL_COUNT_NOTICE = {
+  en: 'Crewforth sends one anonymous "install worked" count (version only, no IDs or paths). Turn off: CREW_NO_TELEMETRY=1 · details: README → Telemetry',
+  tr: 'Crewforth tek seferlik anonim bir "kurulum çalıştı" sayımı gönderir (yalnız sürüm; kimlik ve yol yok). Kapatmak için: CREW_NO_TELEMETRY=1 · ayrıntı: README → Telemetri',
+};
+function installCountOff(env) {
+  const set = (v) => v !== undefined && v !== '' && v !== '0';
+  return set(env.CREW_NO_TELEMETRY) || set(env.DO_NOT_TRACK) || env.CI !== undefined;
+}
+function countInstall() {
+  try {
+    const url = process.env.CREW_TELEMETRY_URL || INSTALL_COUNT_URL;
+    if (!url || installCountOff(process.env) || typeof fetch !== 'function') return;
+    let version = '';
+    try { version = fs.readFileSync(path.join(pkgDir, 'VERSION'), 'utf8').split(/\r?\n/)[0].trim(); } catch (_) { /* none */ }
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.]+)?$/.test(version)) return;
+    const project = process.cwd();
+    const gitEnv = { ...process.env }; delete gitEnv.GIT_DIR; delete gitEnv.GIT_WORK_TREE;
+    const g = spawnSync('git', ['rev-parse', '--git-path', 'crewforth-install-counted'], { cwd: project, env: gitEnv, encoding: 'utf8' });
+    const rel = g.status === 0 ? String(g.stdout).trim() : '';
+    const marker = rel ? path.resolve(project, rel) : path.join(project, '.claude', 'install-counted');
+    if (fs.existsSync(marker)) return;
+    let lang = /^(tr)/i.test(process.env.LC_ALL || process.env.LC_MESSAGES || process.env.LANG || '') ? 'tr' : 'en';
+    if (process.env.CREW_LANG === 'tr' || process.env.CREW_LANG === 'en') lang = process.env.CREW_LANG;
+    try {
+      const conf = fs.readFileSync(path.join(project, '.claude', 'kit.conf'), 'utf8');
+      const m = /^lang=(tr|en)\s*$/m.exec(conf); if (m) lang = m[1];
+    } catch (_) { /* no record of the install's language */ }
+    console.log(INSTALL_COUNT_NOTICE[lang]);
+    try { fs.writeFileSync(marker, version + '\n'); } catch (_) { return; }   // no marker, no request: it would repeat
+    fetch(`${url.replace(/\/+$/, '')}/install?v=${encodeURIComponent(version)}`, {
+      headers: { 'User-Agent': 'crewforth' }, signal: AbortSignal.timeout(1500),
+    }).then(
+      (r) => { if (r.body) r.body.cancel().catch((_) => { /* the answer is never read: nothing is lost */ }); },
+      (_) => { /* no answer within 1.5 s, refused or offline: the count is lost, never the install */ },
+    );
+  } catch (_) { /* a count is never worth a failed install */ }
+}
+// Called last: the constants above are declared by the time it reads them.
+if (script === 'start.sh' && process.exitCode === 0) countInstall();

package/kit/eval/smoke-test.sh

@@ -1083,6 +1083,33 @@ fillc 772000 manual 1
 sgerr="$(mkjson "${SGPFX}-l" "$SGFX" false | CONTEXT_WINDOW=1000000 bash "$HOOKS/session-guard.sh" 2>&1 >/dev/null)"
 [ -z "$sgerr" ] && pass "stop-hook: writes nothing to stderr when a compaction IS present" \
                 || fail "stop-hook wrote to stderr with a compaction: $(printf '%s' "$sgerr" | tr '\n' ' ' | cut -c1-160)"
+# (13) THE REPLY'S 🔋 FIGURE IS HELD AGAINST THE MEASUREMENT. The discipline says it is copied from the hook's
+#      line, never guessed, and nothing checked it: a real session printed 45 … 86 for hours while its
+#      transcript measured 30.3, and the user handed it off on that number. The message escapes its newline as
+#      `\n`, as the payload does.
+mkjsonm(){ printf '{"session_id":"%s","transcript_path":"%s","hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"%s"}' "$1" "$SGFX" "$2"; }
+sgm(){ mkjsonm "$1" "$2" | CONTEXT_WINDOW=1000000 bash "$HOOKS/session-guard.sh" 2>/dev/null; }
+fill 303000
+o="$(sgm "${SGPFX}-m1" 'Stopped.\n\n🔋 Oturum %85 → yüksek doluluk · Öneri: yeni oturum')"
+case "$o" in *'"systemMessage"'*'says %85'*'%30.3'*) pass "stop-hook: a 🔋 figure far from the measurement is reported with the measured one" ;;
+  *) fail "stop-hook let a guessed 🔋 figure (85 against a measured 30.3) through: $o" ;; esac
+[ -z "$(sgm "${SGPFX}-m2" 'Done.\n\n🔋 Oturum %30,3 → düşük doluluk · Öneri: devam')" ] \
+  && pass "stop-hook: a 🔋 figure that matches the measurement is silent (a decimal comma included)" \
+  || fail "stop-hook reported a 🔋 figure that matches the measurement"
+[ -z "$(sgm "${SGPFX}-m3" 'Done.\n\n🔋 Session %34 → low fill')" ] \
+  && pass "stop-hook: a figure within the tolerance is silent (an end-of-turn reading runs ahead of the copied one)" \
+  || fail "stop-hook reported a figure inside the 5-point tolerance"
+[ -z "$(sgm "${SGPFX}-m4" 'The line reads: 🔋 Session %NN → level')$(sgm "${SGPFX}-m5" 'Done.')" ] \
+  && pass "stop-hook: no 🔋 figure (a quoted template, or no line at all) says nothing" \
+  || fail "stop-hook spoke about a reply with no 🔋 figure"
+fill 800000
+o="$(sgm "${SGPFX}-m6" 'Done.\n\n🔋 Session %40 → low fill')"
+case "$o" in *'says %40'*'>75%'*) pass "stop-hook: a wrong figure and a threshold alert share one systemMessage" ;;
+  *) fail "stop-hook dropped one of the two messages, or printed two objects: $o" ;; esac
+if [ -n "$JSONQ" ]; then
+  printf '%s' "$o" | json_get systemMessage >/dev/null 2>&1 && pass "stop-hook: the combined message is valid JSON (oracle: $JSONQ)" \
+    || fail "stop-hook's combined message is not valid JSON: $o"
+else skip tool "stop-hook combined-message JSON check skipped (no working JSON parser)"; fi
 rm -f "$SGFX"; rm -f "${TMPDIR:-/tmp}"/crew-session-guard.${SGPFX}-*.* 2>/dev/null
 
 # ---- CREW-NOJQ-PATH ---------------------------------------------------------------------------------------
@@ -1137,6 +1164,57 @@ crew_nojq_path(){   # $@ = the tools the code under test needs on PATH
 }
 # ---- /CREW-NOJQ-PATH --------------------------------------------------------------------------------------
 
+sec "== 6b2) a worktree the session enters carries .claude/ =="
+# .claude/ is gitignored, so `git worktree add ../x` makes a worktree with none, and a session resumed there loads no
+# hook at all (measured on Claude Code 2.1.309: a resumed session in such a worktree ran no project hook; the same
+# worktree with .claude/ copied in ran the Crewforth hooks). worktree-provision.sh copies it on EnterWorktree.
+if ! command -v git >/dev/null 2>&1; then skip tool "worktree provisioning not checked (no git)" 7
+else
+  _wp="$(mktemp -d)"; _wpm="$_wp/main"
+  mkdir -p "$_wpm/.claude/state" "$_wpm/.claude/worktrees" "$_wp/other"
+  ( cd "$_wpm" && git init -q && git config user.email p@example.test && git config user.name p && printf '.claude/\n' > .gitignore \
+      && git add .gitignore && git commit -qm init ) >/dev/null 2>&1
+  cp -R "$HOOKS" "$ROOT/eval" "$ROOT/settings.json" "$_wpm/.claude/" 2>/dev/null
+  echo s > "$_wpm/.claude/state/x"; echo '{}' > "$_wpm/.claude/review-pass.json"; echo g > "$_wpm/.claude/gate-log.tsv"
+  git -C "$_wp/other" init -q 2>/dev/null
+  for _w in ../wtA ../wtB ../wtC .claude/worktrees/inner; do git -C "$_wpm" worktree add -q "$_w" -b "b${RANDOM}" >/dev/null 2>&1; done
+  _wpH="$_wpm/.claude/hooks/worktree-provision.sh"
+  _wpcall(){ printf '{"hook_event_name":"%s","cwd":"%s","tool_name":"EnterWorktree","tool_input":{"path":"%s"},"tool_response":{"worktreePath":"%s"}}' "$1" "$_wpm" "$2" "$3" \
+    | ( cd "$_wpm" && bash "$_wpH" ) 2>"$_wp/err"; }
+  if [ ! -d "$_wp/wtA" ] || [ ! -d "$_wpm/.claude/worktrees/inner" ] || [ -e "$_wp/wtA/.claude" ]; then
+    fail "FIXTURE: the worktrees were not made, or wtA already had .claude/ — nothing below would be measured"
+  else
+    _wpcall PreToolUse "$_wp/wtA" ""; _r=$?
+    { [ "$_r" = 0 ] && [ -f "$_wp/wtA/.claude/settings.json" ] && [ -x "$_wp/wtA/.claude/hooks/guard-bash.sh" ] && [ -f "$_wp/wtA/.claude/eval/lib/settings-json.awk" ]; } \
+      && pass "worktree: entering a worktree made with git worktree add copies settings, hooks and eval into it (it had none)" \
+      || fail "worktree: entering ../wtA did not give it a working .claude/ (rc=$_r): $(head -c 200 "$_wp/err")"
+    { [ ! -e "$_wp/wtA/.claude/state" ] && [ ! -e "$_wp/wtA/.claude/worktrees" ] && [ ! -e "$_wp/wtA/.claude/review-pass.json" ] && [ ! -e "$_wp/wtA/.claude/gate-log.tsv" ]; } \
+      && pass "worktree: what belongs to one checkout (state/, worktrees/, the review record, the gate log) is not copied" \
+      || fail "worktree: the copy carried one checkout's own state into another"
+    _wpcall PostToolUse "" "$_wp/wtB"; _r=$?
+    { [ "$_r" = 0 ] && [ -f "$_wp/wtB/.claude/settings.json" ]; } \
+      && pass "worktree: after the move, the path the tool reports is provisioned too" \
+      || fail "worktree: PostToolUse did not provision the reported worktree (rc=$_r)"
+    _wpcall PreToolUse "$_wpm/.claude/worktrees/inner" ""; _r1=$?
+    _wpcall PreToolUse "$_wp/other" ""; _r2=$?
+    { [ "$_r1$_r2" = 00 ] && [ ! -e "$_wpm/.claude/worktrees/inner/.claude" ] && [ ! -e "$_wp/other/.claude" ]; } \
+      && pass "worktree: one Claude Code made under .claude/worktrees/ and another repository are left alone" \
+      || fail "worktree: wrote into a worktree it should leave alone (rc $_r1/$_r2)"
+    _wpcall PreToolUse "$_wp/wtA" ""; _r=$?
+    [ "$_r" = 0 ] && pass "worktree: a worktree that already carries .claude/ is passed through" || fail "worktree: re-entering a provisioned worktree answered $_r"
+    # The copy cannot be made: .claude is a FILE there, so mkdir fails whoever runs the suite (root included).
+    : > "$_wp/wtC/.claude"
+    _wpcall PreToolUse "$_wp/wtC" ""; _r=$?
+    { [ "$_r" = 2 ] && grep -q 'could not put its .claude/ into the worktree' "$_wp/err"; } \
+      && pass "worktree: when the copy cannot be made, entering is refused (exit 2) and the reason is said" \
+      || fail "worktree: a failed copy did not refuse the move (rc=$_r): $(head -c 200 "$_wp/err")"
+    _o="$(_wpcall PostToolUse "" "$_wp/wtC")"; _r=$?
+    case "$_r$_o" in 0*'"systemMessage"'*'could not put its .claude/'*'"additionalContext"'*) pass "worktree: a failed copy after the move tells the user and the model" ;;
+      *) fail "worktree: a failed copy after the move was silent (rc=$_r): $_o" ;; esac
+  fi
+  rm -rf "$_wp"
+fi
+
 sec "== 6c) no-jq fallback: sidechain-safe + full token sum =="
 BASHBIN="$(command -v bash 2>/dev/null || echo bash)"   # absolute -> a stripped PATH must not hide bash itself
 JXBIN="$(crew_nojq_path awk sed grep head tail cat ls tr)"
@@ -1946,16 +2024,16 @@ if [ "$IS_KIT" = 1 ]; then
     [ "${HC:-0}" -ge 2 ] && pass "$r states the real hook count ($TH) in both the summary table and the section header" \
       || fail "$r does not state $TH hooks in both places — the count drifted from hooks/ (found $HC of 2)"
   done
-  # The plugin channel wires a SUBSET on purpose (skill-trust.sh needs a manifest only an installer writes).
-  # Assert the subset is exactly that one, so a hook silently dropped from the plugin fails here.
+  # The plugin channel wires a SUBSET on purpose (skill-trust.sh needs a manifest only an installer writes;
+  # worktree-provision.sh copies an installed .claude/, which a plugin has not). Assert the subset is exactly those, so a hook silently dropped from the plugin fails here.
   if [ -f "$KR/plugin/hooks/hooks.json" ] && [ -f "$ROOT/settings.json" ]; then
     SET_H="$(grep -oE '[a-z-]+\.sh' "$ROOT/settings.json" | sort -u)"
     PLG_H="$(grep -oE '[a-z-]+\.sh' "$KR/plugin/hooks/hooks.json" | sort -u)"
     ONLY_SET="$(comm -23 <(printf '%s\n' "$SET_H") <(printf '%s\n' "$PLG_H") | tr '\n' ' ' | sed 's/ *$//')"
-    if [ "$ONLY_SET" = "skill-trust.sh" ]; then
-      pass "plugin wires every settings.json hook except skill-trust.sh (documented exclusion)"
+    if [ "$ONLY_SET" = "skill-trust.sh worktree-provision.sh" ]; then
+      pass "plugin wires every settings.json hook except skill-trust.sh and worktree-provision.sh (documented exclusions)"
     else
-      fail "plugin/settings hook sets diverged — only in settings: '${ONLY_SET:-none}' (expected exactly skill-trust.sh)"
+      fail "plugin/settings hook sets diverged — only in settings: '${ONLY_SET:-none}' (expected exactly skill-trust.sh worktree-provision.sh)"
     fi
     # The two editions must also agree on WHICH TOOLS they watch, not just which scripts they run. Matching
     # `Bash` alone leaves the PowerShell tool ungated, and on Windows without Git Bash that tool is the only
@@ -6929,9 +7007,9 @@ rm -rf "$_hsd"
 # A gate's timeout is not a comfort setting: a PreToolUse hook that reaches it does not block (Claude Code's hooks
 # reference: "doesn't block the tool call … don't count on a stalled hook to act as a gate"), and a field session on
 # 3.0.0 showed nine of them in one day — the commands ran with no gate. Crewforth had set 60 s where Claude Code's
-# own default is 600, and the slowest machine measured needed 32-134 s for one guard-bash call. The eight PreToolUse
-# gates (the four bash gates, the no-bash gate of 12e, guard-schedule.sh, guard-agent-model.sh and prompt-approval.sh on
-# the approval question, whose `ask` is what keeps a hook from answering it) carry 600 now; every other hook keeps 60 —
+# own default is 600, and the slowest machine measured needed 32-134 s for one guard-bash call. The nine PreToolUse
+# gates (the four bash gates, the no-bash gate of 12e, guard-schedule.sh, guard-agent-model.sh, worktree-provision.sh and
+# prompt-approval.sh on the approval question, whose `ask` is what keeps a hook from answering it) carry 600 now; every other hook keeps 60 —
 # when one of those times out, nothing is left unguarded.
 # Read per entry, in both editions; the twin lowers one gate back to 60 and must be seen.
 gate_timeouts(){ json_hooks "$1" | LC_ALL=C awk -F'\t' '$1 == "PreToolUse" { n++; t = 0
@@ -6941,13 +7019,15 @@ gate_timeouts(){ json_hooks "$1" | LC_ALL=C awk -F'\t' '$1 == "PreToolUse" { n++
 _gtd="$(mktemp -d)"
 tr -d '\n' < "$ROOT/settings.json" | sed 's/guard-bash\.sh\([^}]*\)"timeout": 600/guard-bash.sh\1"timeout": 60/' > "$_gtd/twin.json"
 _gtw="$(gate_timeouts "$_gtd/twin.json")"
-if [ "$_gtw" != "8 1" ]; then fail "gate timeout pin: the twin with guard-bash.sh back at 60 s read '$_gtw', want '8 1' — the pin sees nothing"
+if [ "$_gtw" != "9 1" ]; then fail "gate timeout pin: the twin with guard-bash.sh back at 60 s read '$_gtw', want '9 1' — the pin sees nothing"
 else for _gf in $_gpw_f; do
   [ -f "$_gf" ] || continue
   set -- $(gate_timeouts "$_gf")
-  if [ "${1:-0}" != 8 ]; then fail "${_gf##*/}: $1 PreToolUse gate hooks read, want 8 — the pin did not read the file as written"
-  elif [ "${2:-9}" = 0 ]; then pass "${_gf##*/}: all 8 PreToolUse gates have a 600 s timeout (a gate that times out does not block)"
-  else fail "${_gf##*/}: $2 of 8 PreToolUse gates time out before 600 s — a timed-out gate does not block"; fi
+  # The plugin edition has no worktree-provision.sh (build-plugin.sh says why), so it carries one gate fewer.
+  _gwant=9; case "$_gf" in */hooks.json) _gwant=8 ;; esac
+  if [ "${1:-0}" != "$_gwant" ]; then fail "${_gf##*/}: $1 PreToolUse gate hooks read, want $_gwant — the pin did not read the file as written"
+  elif [ "${2:-9}" = 0 ]; then pass "${_gf##*/}: all $_gwant PreToolUse gates have a 600 s timeout (a gate that times out does not block)"
+  else fail "${_gf##*/}: $2 of $_gwant PreToolUse gates time out before 600 s — a timed-out gate does not block"; fi
 done; fi
 rm -rf "$_gtd"
 

package/kit/hooks/session-guard.sh

@@ -117,6 +117,31 @@ if [ -z "$PCT" ]; then
   [ -n "$PCT" ] || exit 0
 fi
 
+# The reply's own 🔋 line, held against the reading. The discipline says that figure is copied from the hook's
+# line and never guessed, and nothing checked it: a session whose hook line had stopped arriving went on to print
+# 45, 51 … 86 while its transcript measured 30.3, and the user handed the session off on that number. A figure
+# more than CREW_FILL_TOLERANCE points (default 5) from the measurement is reported to the user, every turn it
+# happens. The tolerance covers the one honest gap: a slow-path reading is taken at the END of the turn, so it
+# includes output the model had not produced when it copied the start-of-turn line. No 🔋 line, or none with a
+# number after its '%' (a quoted template, `%NN`), says nothing. Pure expansion: no process.
+WRONG=""
+_said="${IN##*🔋}"
+if [ "$_said" != "$IN" ]; then
+  _said="${_said%%\\n*}"                           # that line only: the payload escapes a newline as \n
+  _num="${_said#*%}"
+  if [ "$_num" != "$_said" ]; then
+    _num="${_num%%[!0-9.,]*}"; _num="${_num/,/.}"  # a Turkish reply writes %30,3
+    _si="${_num%%.*}"; _sf="${_num#"$_si"}"; _sf="${_sf#.}"; _sf="${_sf:0:1}"
+    _mi="${PCT%%.*}"; _mf="${PCT#"$_mi"}"; _mf="${_mf#.}"; _mf="${_mf:0:1}"
+    case "$_si$_sf$_mi$_mf" in ''|*[!0-9]*) ;; *)
+      [ -n "$_si" ] && [ -n "$_mi" ] && {
+        _d=$(( (10#$_si * 10 + 10#${_sf:-0}) - (10#$_mi * 10 + 10#${_mf:-0}) )); [ "$_d" -lt 0 ] && _d=$(( -_d ))
+        [ "$_d" -gt $(( ${CREW_FILL_TOLERANCE:-5} * 10 )) ] && WRONG="%$_num"
+      } ;;
+    esac
+  fi
+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
@@ -126,24 +151,26 @@ 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
-
+MSG=""
 # 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."
+if [ -n "$TIER" ] && [ ! -e "$(marker "$TIER")" ]; then
+  # 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
 fi
+[ -n "$MSG$WRONG" ] || exit 0
 
 # JSON-escape backslash + double-quote in the measured line before embedding it.
 SAFE="$(printf '%s' "$LINE" | sed 's/\\/\\\\/g; s/"/\\"/g')"
+OUT="${MSG:+$SAFE | $MSG}"
+[ -n "$WRONG" ] && OUT="⚠️ The 🔋 line in this reply says $WRONG, but the fill measured from the transcript is: $SAFE. The reply's figure is not a measurement — do not decide a handoff on it.${OUT:+ · $OUT}"
 # 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"
+printf '{"systemMessage":"%s"}\n' "$OUT"
 exit 0

package/kit/hooks/worktree-provision.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# PreToolUse + PostToolUse on EnterWorktree — a worktree the session enters carries Crewforth with it.
+#
+# Why: `.claude/` is gitignored in a fresh install, so a worktree made with `git worktree add ../x` has none. While
+# the session that entered it lives, its hooks keep running from the main checkout. But Claude Code records the
+# session under the worktree once it enters one, and a session resumed there reads its settings from the worktree:
+# with no `.claude/settings.json` there, NO hook is registered — no commit approval, no write gate, no fill line.
+# Measured on Claude Code 2.1.309: a resumed session in such a worktree ran no project hook (0 of 1), the same
+# worktree with `.claude/` copied in ran it (1 of 1). A field session ran four and a half hours that way, printing a
+# fill it had made up. A worktree Claude Code creates under `.claude/worktrees/` is not affected (measured: the
+# resumed session there still ran the main checkout's hooks), so it is left alone.
+#
+# What it does: before the move (PreToolUse, when the call names an existing path) and after it (PostToolUse, the
+# path the tool reports), a linked worktree of THIS repository with no `.claude/settings.json` gets a copy of this
+# checkout's `.claude/`, minus what belongs to one checkout only (`worktrees/`, `state/`, the review record, the
+# gate log). If the copy cannot be made, the PreToolUse call is refused (exit 2) with the reason, and the
+# PostToolUse call tells the user and the model, since the move already happened.
+set -uo pipefail
+# ---- CREW-FAILCLOSED ---------------------------------------------------------------------------------------
+# A gate that stops on an error of its own must refuse the call, not let it through. Claude Code blocks a tool call
+# on exit 2 only; a hook that dies with 1, or runs on past the rule that broke, has allowed it. Both happened in
+# one defect (measured, bash 5): a local array declared and not set is "unbound" under `set -u`, the rule that read
+# it was abandoned in the middle, the script went on with the NEXT top-level command and left with 0, and
+# `rm .claude/hooks/pre-commit` passed. bash does one of two things with such an error, by the kind of error:
+#   * it leaves the shell with a status that is neither 0 nor 2  -> the EXIT trap below turns that into a refusal;
+#   * it abandons the top-level command it was in and continues -> the whole gate IS one top-level command,
+#     _gate_main, which only ever ends by `exit`. If it RETURNS, it was abandoned, and the line after it refuses.
+# Not covered, and said so: an error inside a command substitution (only that subshell ends), and a command
+# that is not found (status 127, the script continues inside the same command).
+# Byte-identical in every PreToolUse gate; the suite pins it. No process is started.
+_crew_stop(){  # $1 = what happened
+  declare -F gatelog >/dev/null 2>&1 && gatelog BLOCK 4.5 "the gate stopped on an error of its own"
+  echo "GUARD (§4.5): this gate stopped on an error of its own ($1) before it finished judging the call, so the call is refused." >&2
+  echo "Nothing about the call itself was found. The error is the line above these two; it is a defect in Crewforth, not in what you ran. Run the doctor (bash .claude/eval/doctor.sh, Bash tool, not PowerShell) and report it." >&2
+  exit 2
+}
+trap '_crew_rc=$?; trap - EXIT; case "$_crew_rc" in 0|2) exit "$_crew_rc" ;; esac; _crew_stop "exit status $_crew_rc"' EXIT
+# ---- /CREW-FAILCLOSED
+unq(){ local p="${1#\"}"; p="${p%\"}"; p="${p//\\\\//}"; p="${p//\\//}"; printf '%s' "$p"; }   # JSON string -> path; \ -> /
+_gate_main(){
+local IN HERE SRC READER V EV P_IN P_OUT T MINE THEIRS TOP ERR e WHY SAFE
+IFS= read -r -d '' IN || true
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SRC="$(cd "$HERE/.." && pwd)"                      # this checkout's .claude/
+READER="$SRC/eval/lib/settings-json.awk"
+[ -f "$READER" ] || exit 0                         # no reader, nothing to read the payload with: fail open
+
+V="$(printf '%s' "$IN" | awk -v op=gets -v path='hook_event_name|tool_input.path|tool_response.worktreePath' -f "$READER" - 2>/dev/null)"
+EV="${V%%$'\t'*}"; V="${V#*$'\t'}"; P_IN="${V%%$'\t'*}"; V="${V#*$'\t'}"; P_OUT="${V%%$'\t'*}"
+EV="$(unq "$EV")"
+case "$EV" in
+  PreToolUse)  T="$(unq "$P_IN")" ;;
+  PostToolUse) T="$(unq "$P_OUT")" ;;
+  *) exit 0 ;;
+esac
+[ -n "$T" ] && [ -d "$T" ] || exit 0              # no path (Claude creates one under .claude/worktrees/) or none yet
+
+# Only a linked worktree of THIS repository, asked of git rather than compared as spelled (C:/ against /c/).
+MINE="$(git -C "$SRC/.." rev-parse --git-common-dir 2>/dev/null)" || exit 0
+THEIRS="$(git -C "$T" rev-parse --git-common-dir 2>/dev/null)" || exit 0
+case "$MINE" in /*|?:*) ;; *) MINE="$SRC/../$MINE" ;; esac
+case "$THEIRS" in /*|?:*) ;; *) THEIRS="$T/$THEIRS" ;; esac
+[ "$MINE" -ef "$THEIRS" ] || exit 0
+TOP="$(git -C "$T" rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ "$TOP" -ef "$SRC/.." ] && exit 0                 # the main checkout itself
+case "$(cd "$TOP" && pwd -P)/" in "$(cd "$SRC" && pwd -P)/worktrees/"*) exit 0 ;; esac   # Claude Code's own: unaffected
+[ -f "$TOP/.claude/settings.json" ] && exit 0      # already carries it (or .claude/ is tracked)
+
+ERR=""
+mkdir -p "$TOP/.claude" 2>/dev/null || ERR="could not create $TOP/.claude"
+if [ -z "$ERR" ]; then
+  for e in "$SRC"/* "$SRC"/.[!.]*; do
+    [ -e "$e" ] || continue
+    case "${e##*/}" in worktrees|state|review-pass.json|gate-log.tsv) continue ;; esac
+    cp -R "$e" "$TOP/.claude/" 2>/dev/null || { ERR="could not copy ${e##*/}"; break; }
+  done
+fi
+[ -z "$ERR" ] && { [ -f "$TOP/.claude/settings.json" ] && [ -d "$TOP/.claude/hooks" ] || ERR="the copy has no settings.json or hooks/"; }
+[ -z "$ERR" ] && exit 0
+
+WHY="Crewforth could not put its .claude/ into the worktree $TOP ($ERR). A session resumed there would load no Crewforth hook: no commit approval, no write gate, no fill reading."
+if [ "$EV" = PreToolUse ]; then
+  echo "$WHY Fix the cause above, then enter the worktree again." >&2
+  exit 2
+fi
+SAFE="${WHY//\\/\\\\}"; SAFE="${SAFE//\"/\\\"}"
+printf '{"systemMessage":"⚠️ %s","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s Tell the user, and do not resume this session in that worktree until it is fixed."}}\n' "$SAFE" "$SAFE"
+exit 0
+}
+_gate_main "$@"
+_crew_stop "a command of the gate was abandoned"

package/kit/owned-blobs.tsv

@@ -1,9 +1,10 @@
-# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.2.1 (below VERSION 3.3.0) — do not edit by hand.
+# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.3.0 (below VERSION 3.4.0) — do not edit by hand.
 # The flat files Crewforth owns: a copy whose bytes (CR aside) are one of these ids was never edited.
 # install_path	blob_sha1	first_tag	last_tag
 .claude/AGENT_TEMPLATE.md	075e2c26706c06f56af01652cd24c36918513bee	v3.0.0	v3.0.4
 .claude/AGENT_TEMPLATE.md	2c8223d811245e3627a3011bb64fb9e4b0bf3b94	v3.2.0	v3.2.1
 .claude/AGENT_TEMPLATE.md	3fdc551d221ee3665b21ef8cc3563de861a9abe6	v1.4.0	v1.6.3
+.claude/AGENT_TEMPLATE.md	59d3af63b0480696dec38136e124bd582066fb16	v3.3.0	v3.3.0
 .claude/AGENT_TEMPLATE.md	686fed306c873b45c245c77a95a8e6de6ee383d5	v1.7.0	v2.11.0
 .claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.1
 .claude/AGENT_TEMPLATE.md	981df9ea27b6f1c5ab5cb509d40875a07603858d	v2.12.0	v2.13.0
@@ -29,6 +30,7 @@
 .claude/DISCIPLINE.md	b7e1066451a8590e0a2607ad0a6fe80b21599c53	v1.1.3	v1.1.8
 .claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.1
 .claude/DISCIPLINE.md	bf062c2b51a9cf3cc4d0caac389c148cf6fdc977	v2.12.0	v2.12.0
+.claude/DISCIPLINE.md	c04f53866b84c54aa0e60089cb54cdc7c9aa8df1	v3.3.0	v3.3.0
 .claude/DISCIPLINE.md	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
 .claude/DISCIPLINE.md	cf881a5229d85850194a98b8d0d0438a8eaaa9d6	v3.2.0	v3.2.1
 .claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
@@ -45,4 +47,4 @@
 .claude/README.md	97d4dd1f7f1695052cc1d06cc43f5bcdc603c989	v1.0.0	v1.0.4
 .claude/README.md	a3419891cfda7385564008e4befc1007bc5364cb	v1.1.1	v1.7.0
 .claude/README.md	a3b76e0fa31267610d28b742c122a962f6db59c4	v3.0.1	v3.0.4
-.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.2.1
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.3.0

package/kit/settings.json

@@ -119,6 +119,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/worktree-provision.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -220,6 +231,17 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/worktree-provision.sh",
+            "timeout": 60
+          }
+        ]
       }
     ],
     "PreCompact": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewforth",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Crewforth \u2014 your engineering crew for Claude Code: agents, skills and tool-level gates, in any stack.",
   "bin": {
     "crewforth": "bin/cli.js"