crewforth 3.2.0-rc.2 → 3.2.0-rc.4

package/kit/hooks/guard-agent-model.sh

@@ -14,10 +14,15 @@
 #   * RISK CLASS. `critical` when the change is migration, security, architecture or fix-unknown, or a file is on a
 #     critical path (auth, payments, billing, migrations, security, crypto, secrets, *.sql, schema.prisma;
 #     .claude/crew-model-rules adds and removes paths). Otherwise `normal`.
-#   * critical work runs on opus, whatever the agent. The one exception is test-run: running the tests is objective.
+#   * critical work runs on opus, whatever the agent. Two exceptions: test-run (running the tests is objective), and
+#     a text change whose every file is prose (.md .txt .rst .adoc), which runs on sonnet or above: a reworded
+#     paragraph under legal/ is read by a person, and opus for it is the cost this gate exists to stop. A project
+#     that wants opus there says so in .claude/crew-model-rules (floor * text critical opus).
 #   * the referee is as strong as the risk: test-write and audit on sonnet or above (opus when critical, by the rule
 #     above); review, privacy, planner and database agents on sonnet or above; the security agent on opus.
-#   * work with no verify command runs on sonnet or above: haiku goes only to work a command can check.
+#   * work with no verify command runs on sonnet or above: haiku goes only to work a command can check. Not for
+#     change: text, nor for the commit agent: a reader is all prose ever has, and a commit message is checked by
+#     the commit-msg hook (seen on a real project: a commit message proposed on sonnet for that reason alone).
 #   * a class that failed too often is held one model up (crew-model-floors.auto, written by hooks/agent-outcome.sh),
 #     until the user lowers it again with /crew-loosen (one model, once for each raise).
 #   * a card whose verify failed is not run again on the same or a lower model, and not a third time at all.
@@ -412,13 +417,58 @@ _am_crit_path(){  # $1 = a path or a glob -> 0 critical (_AMW says by what), 1 n
   return "$hit"
 }
 
+_am_prose(){  # $1 = a path or a glob -> 0 when it is prose a person reads (the exception for a text change)
+  case "$1" in *.md|*.MD|*.markdown|*.txt|*.TXT|*.rst|*.adoc) return 0 ;; esac
+  return 1
+}
+_am_all_prose(){  # after _am_card -> 0 when every file of the card is prose
+  local f r=0 unglob=0
+  case "$-" in *f*) ;; *) unglob=1; set -f ;; esac
+  for f in ${CARD_FILES//,/ }; do _am_prose "$f" || { r=1; break; }; done
+  [ "$unglob" = 1 ] && set +f
+  return "$r"
+}
+
 # ---- THE CARD ---------------------------------------------------------------------------------------------------
 _AM_CHANGES=' text feature fix-known fix-unknown refactor migration security architecture test-run test-write audit '
+_am_trim(){  # $1 -> _AMT: no white space around it, and no separator or full stop left at its end (one-line cards)
+  local v="$1" o
+  while :; do case "$v" in [$' \t']*) v="${v:1}" ;; *) break ;; esac; done
+  while :; do o="$v"
+    case "$v" in *[$' \t']) v="${v%?}" ;; *'·') v="${v%'·'}" ;; *'—') v="${v%'—'}" ;; *'–') v="${v%'–'}" ;; *[\|\;,.]) v="${v%?}" ;; esac
+    [ "$v" = "$o" ] && break
+  done
+  _AMT="$v"
+}
+# THE CARD ON ONE LINE. Sessions write it as `files: … · change: … · verify: …` (measured on this machine's transcripts,
+# 2026-10-18: 17 of the 39 calls refused for their card, in 6 projects; the next call was the same card on three lines).
+# It is read by its labels, in that order, after an optional `Card:` / `Card —`; `above: <why>` may close the line. The
+# fields are then held to exactly the rules of the three-line card below, so nothing passes here that would not there.
+_am_card_line(){  # $1 = the first line of the task -> 0 and CARD_* set (unchecked); 1 when it is not a one-line card
+  local l="$1" r f c v a=""
+  case "$l" in [Cc]ard*) l="${l#[Cc]ard}"; l="${l#\*\*}"
+    while :; do case "$l" in [$' \t:*']*|'—'*|'–'*|-*) case "$l" in '—'*) l="${l#'—'}" ;; '–'*) l="${l#'–'}" ;; *) l="${l:1}" ;; esac ;; *) break ;; esac; done ;;
+  esac
+  case "$l" in files:*) ;; *) return 1 ;; esac
+  r="${l#files:}"
+  case "$r" in *change:*verify:*) ;; *) return 1 ;; esac
+  f="${r%%change:*}"; r="${r#*change:}"; c="${r%%verify:*}"; v="${r#*verify:}"
+  case "$v" in *above:*) a="${v#*above:}"; v="${v%%above:*}" ;; esac
+  _am_trim "$f"; CARD_FILES="$_AMT"; _am_trim "$c"; CARD_CHANGE="$_AMT"; _am_trim "$v"; CARD_VERIFY="$_AMT"
+  [ -n "$a" ] && { _am_trim "$a"; CARD_ABOVE="${_AMT:0:200}"; }
+  return 0
+}
 _am_card(){  # $1 = a task text -> 0 and CARD_FILES, CARD_CHANGE, CARD_VERIFY (CARD_ABOVE); 1 and CARD_WHY
-  local s="$1" l k v n=0 seen=""
+  local s="$1" l k v n=0 seen="" one=0
   CARD_FILES=""; CARD_CHANGE=""; CARD_VERIFY=""; CARD_WHY=""; CARD_ABOVE=""
   s="${s//$'\r'/}"
-  while [ "$n" -lt 3 ] && [ -n "$s" ]; do
+  # One line first: the first line that is not empty, read by its labels; the three-line reading otherwise.
+  l="$s"; while :; do case "$l" in [$' \t\n']*) l="${l:1}" ;; *) break ;; esac; done; l="${l%%$'\n'*}"
+  if _am_card_line "$l"; then
+    one=1; n=3
+    s="${s#*"$l"}"; s="${s#$'\n'}"
+  fi
+  while [ "$one" = 0 ] && [ "$n" -lt 3 ] && [ -n "$s" ]; do
     l="${s%%$'\n'*}"; if [ "$l" = "$s" ]; then s=""; else s="${s#*$'\n'}"; fi
     while :; do case "$l" in [$' \t']*) l="${l:1}" ;; *) break ;; esac; done
     [ -n "$l" ] || continue
@@ -438,12 +488,16 @@ _am_card(){  # $1 = a task text -> 0 and CARD_FILES, CARD_CHANGE, CARD_VERIFY (C
   done
   [ "$n" = 3 ] || { CARD_WHY="the task does not begin with the three lines files:, change:, verify:"; return 1; }
   [ -n "$CARD_FILES" ] || { CARD_WHY="files: is empty (name the files or globs, or the folder)"; return 1; }
+  # A note in parentheses after the kind is the session's own comment, as `none (…)` is for verify: `architecture
+  # (planning only)` is architecture (4 of the cards refused on this machine, 2026-10-18). Only a kind on the list, and
+  # only a note that is the whole rest of the value in parentheses.
+  case "$CARD_CHANGE" in *' ('*')') v="${CARD_CHANGE%% (*}"; case "$_AM_CHANGES" in *" $v "*) CARD_CHANGE="$v" ;; esac ;; esac
   case "$_AM_CHANGES" in *" $CARD_CHANGE "*) ;; *) CARD_WHY="change: is '${CARD_CHANGE:0:40}', not one of:$_AM_CHANGES"; return 1 ;; esac
   [ -n "$CARD_VERIFY" ] || { CARD_WHY="verify: is empty (a command, or none)"; return 1; }
   case "$CARD_VERIFY" in none|None|NONE|-|'none '*|'none('*|'None '*|'NONE '*) CARD_VERIFY=none ;; esac   # "none (the author ran it)" is none
   # Optional, right after the three: `above: <why>` keeps a model above the card's floor. Without it a call above
   # the floor is run on the floor (the cost of a model nobody needed is what this gate exists to stop).
-  while [ -n "$s" ]; do
+  while [ -z "$CARD_ABOVE" ] && [ -n "$s" ]; do
     l="${s%%$'\n'*}"; if [ "$l" = "$s" ]; then s=""; else s="${s#*$'\n'}"; fi
     while :; do case "$l" in [$' \t']*) l="${l:1}" ;; *) break ;; esac; done
     [ -n "$l" ] || continue
@@ -557,13 +611,10 @@ _am_floor_now(){  # $1 agent, $2 change, $3 risk -> _AMF_TIER (the raised floor,
 
 # ---- the gate log: a refusal of this gate is recorded like any other gate's -------------------------------------
 _am_log(){  # $1 = the rule. Same file and line shape as guard-bash.sh's gatelog; the call's text is never recorded.
-  local gl="${CREW_GATE_LOG:-}" v=BLOCK
+  local gl="" v=BLOCK
   case "$1" in "note: "*) v=NOTE ;; esac          # something worth knowing that refused nothing
-  if [ -z "$gl" ]; then
-    [ -d ".claude" ] || return 0
-    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null || return 0; fi
-    gl=".claude/gate-log.tsv"
-  fi
+  declare -F crew_gate_log_write >/dev/null || return 0
+  crew_gate_log_write; gl="$_CREW_GL"; [ -n "$gl" ] || return 0
   printf '%s\t§model\t%s\t\n' "$v" "$1" >> "$gl" 2>/dev/null || true
 }
 
@@ -594,6 +645,7 @@ _am_log(){  # $1 = the rule. Same file and line shape as guard-bash.sh's gatelog
 #   5. THE SHELL GATE AGREES, asked under a session id that is not the session's: only "nothing to say" or an
 #      explicit allow passes.
 _AM_HERE="${BASH_SOURCE%/*}"; [ "$_AM_HERE" = "${BASH_SOURCE}" ] && _AM_HERE=.
+[ -f "$_AM_HERE/../eval/lib/gate-log.sh" ] && . "$_AM_HERE/../eval/lib/gate-log.sh"   # where the gate log goes
 # CREW-NOT-A-RUNG: names of commands a PROJECT's verify line may begin with; nothing here is called by Crewforth.
 _AM_RUNNERS=('npm test' 'npm t' 'pnpm test' 'yarn test' 'bun test' 'deno test'
   'dotnet test' 'dotnet build' 'flutter test' 'flutter analyze' 'dart test' 'dart analyze' 'go test' 'go build' 'go vet'
@@ -665,19 +717,9 @@ _am_perm_hit(){  # $1 = command, $2 = allow|deny|ask -> 0 a Bash(...) rule of th
   done <<< "$_AMSF"
   return 1
 }
-# A verify command in a sub-folder: `cd apps/mobile && flutter test`, the usual shape in a repository of several
-# projects (measured on one: 41 of 71 refused verify commands had it). Split into the folder and the one command,
-# so the command is judged alone and run in that folder with no chain. Only a relative folder inside the project,
-# with no .. step, that exists; anything else is left whole, and is refused as a chain as before.
-_am_verify_split(){  # $1 = the command -> _AMVD the folder ("" = the project root), _AMVC the command
-  local c="$1" d r
-  _AMVD=""; _AMVC="$c"
-  case "$c" in 'cd '*' && '*) ;; *) return 0 ;; esac
-  d="${c#cd }"; d="${d%% && *}"; r="${c#cd "$d" && }"
-  case "$d" in ''|/*|~*|*[!A-Za-z0-9._/-]*|..|../*|*/..|*/../*) return 0 ;; esac
-  [ -n "$r" ] && [ -d "${_AMP:-.}/$d" ] || return 0
-  _AMVD="$d"; _AMVC="$r"
-}
+# How a verify command is read (the `cd <folder> && <command>` split): eval/lib/verify-cmd.sh, shared with doctor.
+[ -f "$_AM_HERE/../eval/lib/verify-cmd.sh" ] && . "$_AM_HERE/../eval/lib/verify-cmd.sh"
+_am_verify_split(){ _AMVD=""; _AMVC="$1"; declare -F crew_verify_split >/dev/null && crew_verify_split "$1" "${_AMP:-.}"; return 0; }
 _am_verify_ok(){  # $1 = the command, $2 = permission mode -> 0 it may run (_AMVB says by what); 1 and _AMVW says why not
   local c="$1" pm="${2:-default}" f r rc k g
   _AMVW=""; _AMVB=""
@@ -759,6 +801,8 @@ _am_write_check(){  # $1 = the payload, $2 = the file about to be written -> ret
     if [ -f "$f" ]; then m="$(grep -m1 -o '"model":"[^"]*"' "$f" 2>/dev/null)" || m=""; _am_tier "$m"; tier="$_AMT"; fi
   fi
   case "$tier" in opus|fable) return 0 ;; esac
+  # A text change on sonnet may write prose there: the call was let through on that floor for exactly that.
+  if [ "$tier" = sonnet ] && _am_prose "$_AMRP" && _am_rec_get "$_AMD/agents/$aid" change && [ "$_AMV" = text ]; then return 0; fi
   _am_log "critical path: write by an agent not on opus"
   echo "GUARD (agent model): $_AMRP is on a critical path ($_AMW) and this agent runs on ${tier:-a model that could not be read}; only an agent on opus writes there. Do not reach the file another way. Stop, and end your report with the two lines: escalate: $_AMRP / confidence: low" >&2
   exit 2
@@ -832,9 +876,11 @@ if ! _am_card "$prompt"; then
 fi
 _am_state; _am_risk; _am_digest
 # ---- the floor of THIS card: the highest of what applies, and the reason that set it ----
-if [ "$CARD_VERIFY" = none ] && [ "$floor" -lt 2 ]; then floor=2; why="no verify command, so nothing checks the work but a reader"; fi
+if [ "$CARD_VERIFY" = none ] && [ "$CARD_CHANGE" != text ] && [ "$st" != crew-commit-agent ] && [ "$floor" -lt 2 ]; then floor=2; why="no verify command, so nothing checks the work but a reader"; fi
 case "$CARD_CHANGE" in test-write|audit) if [ "$floor" -lt 2 ]; then floor=2; why="change: $CARD_CHANGE, the referee of the work"; fi ;; esac
-if [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" != test-run ] && [ "$floor" -lt 3 ]; then floor=3; why="critical work: $CARD_RISKWHY"; fi
+if [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" = text ] && _am_all_prose; then
+  if [ "$floor" -lt 2 ]; then floor=2; why="a text change on a critical path: $CARD_RISKWHY"; fi
+elif [ "$CARD_RISK" = critical ] && [ "$CARD_CHANGE" != test-run ] && [ "$floor" -lt 3 ]; then floor=3; why="critical work: $CARD_RISKWHY"; fi
 # A class the user's rules or the record of outcomes hold higher. Neither can lower anything here.
 _am_rules
 for r in ${_AM_RULES[@]+"${_AM_RULES[@]}"}; do

package/kit/hooks/guard-bash.sh

@@ -148,7 +148,14 @@ _join_cmd(){  # CMD -> CMD with its continued lines joined
 # ---- /CREW-JOIN
 # The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
 _crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
-[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+# Where the gate log goes: one rule for every gate and reader (eval/lib/gate-log.sh).
+[ -f "$_crew_d/../eval/lib/gate-log.sh" ] && . "$_crew_d/../eval/lib/gate-log.sh"
+# What a stopped or asked command would have touched (eval/lib/preview.sh), read only when one is stopped or asked.
+_CREW_PV_LIB="$_crew_d/../eval/lib/preview.sh"; unset _crew_d
+# The preview of a command. ALWAYS called as "$(_pv_line …)": the command substitution is the subshell that keeps an
+# exit or a failure in the library from ending this hook or changing its decision (smoke plants both).
+_pv_line(){ [ -f "$_CREW_PV_LIB" ] || return 0; . "$_CREW_PV_LIB" 2>/dev/null && crew_preview "$1" "$2" 2>/dev/null && printf '%s' "${_CREW_PV:-}"; return 0; }
 # Read with the builtin, as guard-powershell.sh does: `INPUT="$(cat)"` is a subshell plus a process on EVERY call
 # of this hook. `read` returns 1 at end of input; the text is read regardless.
 IFS= read -r -d '' INPUT || true
@@ -168,20 +175,17 @@ IFS= read -r -d '' INPUT || true
 # token, and `/crew-gates` never prints it — the report is rule names and counts. Recording it by default would
 # buy nothing and add a place for a secret to sit. `CREW_GATE_LOG_CMD=1` puts it back for debugging a false
 # positive, which is the only thing it is good for.
-# Where the default log may go. An explicit CREW_GATE_LOG is the operator's call and is used as given. The
-# DEFAULT path is only used when writing there cannot surprise anyone: outside a git repo, or inside one where
-# the path is already ignored. A kit install gitignores .claude/, so this is the normal case — but the plugin
-# edition drops into repos the installer never touched, and this repo proved the failure itself: the suite left
-# a gate-log.tsv sitting in `git status` as an untracked file waiting to be committed. One `git check-ignore`
-# runs only when a decision is logged (a block, an approval prompt or a CLAUDE_GIT_OK allow); ordinary commands
-# never reach it.
+# Where the log goes. An explicit CREW_GATE_LOG is the operator's call and is used as given. .claude/gate-log.tsv
+# only where writing there cannot surprise anyone: outside a git repo, or where git ignores it (a kit install
+# ignores .claude/; the plugin edition drops into repos the installer never touched, and this repo proved the
+# failure: the suite left a gate-log.tsv in `git status` waiting to be committed). Elsewhere it goes inside the
+# repository's .git, which is never committed. git is asked only when a decision is logged (a block, an approval
+# prompt or a CLAUDE_GIT_OK allow); ordinary commands never reach it.
+# Since 3.2.0 a repository that tracks .claude/ gets the log inside its .git (eval/lib/gate-log.sh), where it was
+# not written at all before.
 _gatelog_path(){
-  if [ -n "${CREW_GATE_LOG:-}" ]; then printf '%s' "$CREW_GATE_LOG"; return; fi
-  [ -d ".claude" ] || return 0
-  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null || return 0
-  fi
-  printf '%s' ".claude/gate-log.tsv"
+  declare -F crew_gate_log_write >/dev/null || return 0
+  crew_gate_log_write; printf '%s' "$_CREW_GL"
 }
 gatelog(){  # $1 = verdict (BLOCK|ASK|ALLOW)  $2 = section  $3 = rule
   # Resolve the path ONCE per hook run and remember it HERE, not inside _gatelog_path: that function is invoked
@@ -720,6 +724,8 @@ block(){
   gatelog BLOCK "$2" "$1"
   echo "GUARD (§$2): '$1' stopped AT THE TOOL LEVEL." >&2
   [ -z "${_BLOCK_NOTE:-}" ] || echo "$_BLOCK_NOTE" >&2
+  # What it would have touched, when the rule names a kind (_PV_KIND): read only, after the decision is made.
+  if [ -n "${_PV_KIND:-}" ]; then _pvo="$(_pv_line "$_PV_KIND" "${_PV_CMD:-$CMD}")"; [ -n "$_pvo" ] && echo "$_pvo" >&2; fi
   case "${3:-}" in
     loss)     echo "Nothing here is undone by retrying — but the refusal is not the end of the task. Do the same job the reversible way: name the paths instead of sweeping, and look first (git clean -n, ls) so you act on what you can see. Only if the broad form is genuinely required does the user run it in their own terminal." >&2 ;;
     history)  echo "This rewrites or discards work that is already committed. Ask the person who shares the branch; a new commit usually reaches the same end without rewriting." >&2 ;;
@@ -865,15 +871,15 @@ _push_forces(){   # $1 = one captured `git push …` span -> 0 when a force flag
 _git_d45(){  # $1 = command text; block() exits on the first rule it breaks
   local CMD="$1" HAS_GIT=0 _PUSHSEG _seg                                         # has() reads CMD: this one
   case "$CMD" in *[Gg][Ii][Tt]*) HAS_GIT=1 ;; esac
-  { git_has "$CMD" 'reset'  && has '--hard'; }                                                && block "git reset --hard" "4.5" history
+  { git_has "$CMD" 'reset'  && has '--hard'; }                                                && { _PV_KIND=reset; _PV_CMD="$CMD"; block "git reset --hard" "4.5" history; }
   if [ "$HAS_GIT" = 1 ] && git_has "$CMD" 'push'; then
     _grep_out "$CMD" -oE 'git[[:space:]]+([^;&|]*[[:space:]])?push([^;&|]*)'; _PUSHSEG="$_GO"
     while IFS= read -r _seg; do
       [ -n "$_seg" ] || continue
-      _push_forces "$_seg" && { block "git push --force" "4.5" history; break; }
+      _push_forces "$_seg" && { _PV_KIND=push; _PV_CMD="$_seg"; block "git push --force" "4.5" history; break; }
     done <<< "$_PUSHSEG"
   fi
-  { git_has "$CMD" 'clean'  && has '-[A-Za-z]*f'; }                                           && block "git clean -f" "4.5" loss
+  { git_has "$CMD" 'clean'  && has '-[A-Za-z]*f'; }                                           && { _PV_KIND=clean; _PV_CMD="$CMD"; block "git clean -f" "4.5" loss; }
   return 0
 }
 # ---- the quoted argument of a command that does not run it ---------------------------------------------------
@@ -1109,7 +1115,7 @@ case "$CMD" in *branch*) _HAS_BRANCH=1 ;; *) _HAS_BRANCH=0 ;; esac
 # short cluster, so `rm -Rf /`, `rm -fR /`, `rm -f -r /` and `rm --recursive --force /` all walked past while
 # `rm -rf /` was blocked. Same class as the chmod hole found in evals/permission-pressure: one spelling gated,
 # another reaching the identical state. Case, flag order and the long form are all the same command.
-case "$CMD" in *[Rr][Mm]*) : ;; *) false ;; esac && _grep "$CMD" -qE 'rm +(-[A-Za-z]* +|--[a-z-]+ +)*(-[A-Za-z]*[rR][A-Za-z]*|--recursive)( +(-[A-Za-z]+|--[a-z-]+))* +.*(/|\*|~)' && block "destructive rm -rf" "4.5" loss
+case "$CMD" in *[Rr][Mm]*) : ;; *) false ;; esac && _grep "$CMD" -qE 'rm +(-[A-Za-z]* +|--[a-z-]+ +)*(-[A-Za-z]*[rR][A-Za-z]*|--recursive)( +(-[A-Za-z]+|--[a-z-]+))* +.*(/|\*|~)' && { _PV_KIND=rm; _PV_CMD="$CMD"; block "destructive rm -rf" "4.5" loss; }
 # ADDED (3.1.0): `.` and `..` as a target carry none of those three characters and are the widest targets there are —
 # `rm -rf .` at a project root takes the whole tree, `..` its parent (both passed). Narrower than the test above on
 # purpose, so that it adds no noise: `rm` must stand at a command position, `sudo` or not (`git rm -r --cached .`, `npm rm`,
@@ -1121,7 +1127,7 @@ case "$CMD" in *[Rr][Mm]*)
   _rmc="$CMD"
   # a backslash-newline continues the line (`rm -rf \⏎.`); folded only when one is there and the command is short
   case "$CMD" in *\\"$_RMNL"*) [ "${#CMD}" -le 4096 ] && _rmc="${CMD//\\$_RMNL/ }" ;; esac
-  [[ $_rmc =~ $_RMDOT ]] && block "destructive rm -rf" "4.5" loss ;; esac
+  [[ $_rmc =~ $_RMDOT ]] && { _PV_KIND=rm; _PV_CMD="$_rmc"; block "destructive rm -rf" "4.5" loss; } ;; esac
 # A whole-tree `git checkout -- .` / `git restore .` destroys every uncommitted change with no reflog and no
 # undo — the same loss as `reset --hard`, which has been gated since the beginning, by a command that was not.
 # Not hypothetical: a verification subagent ran exactly this over uncommitted work in this repo and took the
@@ -2518,16 +2524,7 @@ _appr_wired(){  # 0 = prompt-approval.sh is beside this hook and a settings file
 }
 # IS THE APPROVAL QUESTION WIRED? The same reading as above, for the two halves on AskUserQuestion (guard-question.sh
 # on PreToolUse, prompt-approval.sh on PostToolUse). Asked only to choose which way the refusal offers first.
-_q_wired(){
-  local f t d="${CLAUDE_PROJECT_DIR:-.}"
-  d="${d//\\//}"; d="${d%/}"
-  for f in "${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT//\\//}/hooks/hooks.json}" "$d/.claude/settings.json" "$d/.claude/settings.local.json" "${HOME:+${HOME//\\//}/.claude/settings.json}"; do
-    [ -n "$f" ] && [ -f "$f" ] || continue
-    t=""; IFS= read -r -d '' t < "$f" || true
-    case "$t" in *'"PreToolUse"'*AskUserQuestion*guard-question.sh*'"PostToolUse"'*AskUserQuestion*prompt-approval.sh*) return 0 ;; esac
-  done
-  return 1
-}
+_q_wired(){ declare -F _crew_q_wired >/dev/null 2>&1 && _crew_q_wired; }   # defined once, in prompt-approval.sh
 # MAY A PermissionRequest HOOK ANSWER THE PROMPT? One scan, defined in prompt-approval.sh (_crew_prh_scan) and read
 # from there. Without that file there is no other approval to fall back to, so the answer is "no" and the gate
 # asks as it always has.
@@ -2597,12 +2594,21 @@ _gate_written(){
       { printf 'sid=%s\nop=%s\nts=%s\n' "$_psid" "$_pw" "$_pn" > "$_pd/crew-approval-pending"; } 2>/dev/null || _pw=""
     fi
   fi
+  # ONE WAY TO ASK. With the question open, the refusal used to print it and then the typed way as an equal choice,
+  # and the session picked the typed one 7 times in 9 (a real `auto` session on rc.3, 2026-10-18): the user was told
+  # to type a command for what one click does. The typed way is now the fallback, said as one.
+  _QOFF=0
   if [ "$PERM_MODE" = auto ] && [ "$_PRF" = 0 ] && _q_wired && declare -F _crew_q_pre >/dev/null 2>&1 && [ -f "${BASH_SOURCE%/*}/guard-question.sh" ]; then
-    echo "ASK THE USER WITH ONE CLICK (stage first: the approval covers what is staged at that moment): show the commit message whole, in ONE code block, then call AskUserQuestion with exactly this input, nothing added or changed:" >&2
+    _QOFF=1
+    echo "$_CREW_Q_ASK" >&2
     echo "{\"questions\":[$_CREW_Q_JSON]}" >&2
-    echo "Their answer is recorded by Crewforth itself (the line it adds says so); then run the command it names. If they would rather type, the way below works as well." >&2
+    echo "Their answer is recorded by Crewforth itself (the line it adds says so); then run the command it names. Ask it this way only: do not also give the user a command to type." >&2
+  fi
+  if [ "$_QOFF" = 1 ]; then
+    echo "ONLY IF THAT QUESTION CANNOT BE ASKED (the tool call is refused, or the user dismisses it), ask instead, in their language, in this shape and with nothing after it:" >&2
+  else
+    echo "ASK THE USER NOW, in their language, in this shape and with nothing after it (stage first: the approval covers what is staged at that moment):" >&2
   fi
-  echo "ASK THE USER NOW, in their language, in this shape and with nothing after it (stage first: the approval covers what is staged at that moment):" >&2
   echo "  1. the commit message, whole, in ONE code block;" >&2
   if [ -n "$_pw" ]; then
     echo "  2. under it one sentence in their language (If you approve, send only this:), and then the command on a line of its own, exactly as it is:" >&2
@@ -3342,17 +3348,26 @@ if git_has "$CMD_SEEN" 'commit|push'; then
       BRANCH_WARN=""
       # symbolic-ref names the branch even before its first commit, where rev-parse answers "HEAD" and the very
       # first commit onto main went by without this line. A detached HEAD reads empty: not the default branch.
-      case "$(git symbolic-ref --short -q HEAD 2>/dev/null)" in
+      # Read from HEAD with builtins (the gate log's crew_git_dir finds the git dir, a linked worktree's too): the
+      # preview below pays one subshell to keep this hook's decision out of its reach, and this pays it back.
+      _hb=""; if declare -F crew_git_dir >/dev/null 2>&1 && crew_git_dir . && [ -f "$_CREW_GD/HEAD" ]; then
+        IFS= read -r _hb < "$_CREW_GD/HEAD"; _hb="${_hb%$'\r'}"; case "$_hb" in "ref: refs/heads/"*) _hb="${_hb#ref: refs/heads/}" ;; *) _hb="" ;; esac
+      else _hb="$(git symbolic-ref --short -q HEAD 2>/dev/null)"; fi
+      case "$_hb" in
         main|master) BRANCH_WARN="⚠️  This commits DIRECTLY to the default branch. Prefer a feature branch unless you meant to.
 
 " ;;
       esac
       _commit_agent_note
+      # What it takes or sends: the staged change for a commit, the commits for a push (read only).
+      _PVA=""; case "$CMD" in *push*) _PVA="$(_pv_line push-ask "$CMD")" ;; *) _PVA="$(_pv_line commit "$CMD")" ;; esac
       ask_user "§4.4 commit/push approval gate. Claude wants to run:
 
 $SHORT
 
-${BRANCH_WARN}${_CAN}Approve only if the commit message above was shown to you and you agree with it. Approving lets Claude run the command itself."
+${_PVA:+$_PVA
+
+}${BRANCH_WARN}${_CAN}Approve only if the commit message above was shown to you and you agree with it. Approving lets Claude run the command itself."
       ;;
     auto|dontAsk)
       _commit_agent_note; [ -n "$_CAN" ] && printf '%s' "$_CAN" >&2

package/kit/hooks/guard-write.sh

@@ -72,7 +72,8 @@ trap '_crew_rc=$?; trap - EXIT; case "$_crew_rc" in 0|2) exit "$_crew_rc" ;; esa
 _gate_main(){
 # The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
 _crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
-[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"
+[ -f "$_crew_d/../eval/lib/gate-log.sh" ] && . "$_crew_d/../eval/lib/gate-log.sh"; unset _crew_d   # where the gate log goes
 # Read with the builtin, as guard-powershell.sh does: `INPUT="$(cat)"` is a subshell plus a process on EVERY call
 # of this hook. `read` returns 1 at end of input; the text is read regardless.
 IFS= read -r -d '' INPUT || true
@@ -365,12 +366,7 @@ block(){  # $1 = rule name for the log (must keep the `gate-file edit` prefix
   # and with the same rule about the payload: the path is NOT recorded unless CREW_GATE_LOG_CMD=1, because
   # /crew-gates reports rule names and counts and never the argument. Logged after the verdict; it cannot
   # change it. CREW_GATE_LOG overrides the path; point it at /dev/null to turn recording off.
-  _GL="${CREW_GATE_LOG:-}"
-  if [ -z "$_GL" ] && [ -d ".claude" ]; then
-    if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1 || git check-ignore -q ".claude/gate-log.tsv" 2>/dev/null; then
-      _GL=".claude/gate-log.tsv"
-    fi
-  fi
+  _GL=""; declare -F crew_gate_log_write >/dev/null && { crew_gate_log_write; _GL="$_CREW_GL"; }
   if [ -n "$_GL" ]; then
     if [ "${CREW_GATE_LOG_CMD:-0}" = 1 ]; then
       printf 'BLOCK\t§4.5\t%s\t%s\n' "$1" \

package/kit/hooks/precompact-snapshot.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# PreCompact hook — just before the context is compacted, write down the state of the work in a few lines, so the
+# session that comes back after the compaction is told it (session-rehydrate.sh reads it on SessionStart, source
+# compact). A compaction summary is the model's own retelling; this is what the files and the gates say.
+#
+# What it writes, at most ~2 KB: the branch, the uncommitted files (five named, the rest counted), the last refusal in
+# the gate log, how many findings each document under .crewforth/ holds, and whether a handover
+# (docs/SESSION_STATE.md) is there. With the session id and the trigger, so a snapshot is only read back into the
+# session that wrote it.
+#
+# Where: inside the repository's git directory (crewforth-session-snapshot.json), so it is never committed even in a
+# project that tracks .claude/; outside a repository, .claude/state/session-snapshot.json.
+#
+# NEVER BLOCKS. PreCompact exit 2 blocks the compaction (docs: hooks, PreCompact), and blocking an automatic one at
+# the context limit fails the request that needed it. Every path here ends in exit 0, and nothing is printed: a
+# PreCompact hook's output does not reach the summary.
+set -u
+IN="$(cat 2>/dev/null || true)"
+_here="${BASH_SOURCE%[/\\]*}"; [ "$_here" = "${BASH_SOURCE}" ] && _here=.
+LIB="$_here/../eval/lib"
+
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+[ -n "$ROOT" ] || ROOT="$(printf '%s' "$IN" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+[ -n "$ROOT" ] || ROOT="$PWD"
+ROOT="${ROOT//\\\\//}"; ROOT="${ROOT//\\//}"
+cd "$ROOT" 2>/dev/null || exit 0
+
+field(){ local v="${IN#*\"$1\"}"; [ "$v" = "$IN" ] && return 1; v="${v#*:}"; v="${v#"${v%%[![:space:]]*}"}"; case "$v" in \"*) v="${v#\"}"; printf '%s' "${v%%\"*}" ;; *) printf '%s' "${v%%[,\}]*}" ;; esac; }
+SID="$(field session_id)" || SID=""
+TRIG="$(field trigger)" || TRIG=""
+case "$SID" in ''|*[!A-Za-z0-9._-]*) exit 0 ;; esac   # a snapshot no session can claim is not written
+
+# ---- what the files and the gates say ----
+LINES=()
+GD=""
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GD="$(git rev-parse --absolute-git-dir 2>/dev/null)" || GD=""
+  BR="$(git rev-parse --abbrev-ref HEAD 2>/dev/null)" || BR=""
+  [ -n "$BR" ] && LINES+=("branch $BR")
+  # quotePath off: a name in Turkish (or any non-ASCII) is given as written, not as octal escapes (seen on Windows).
+  CH="$(git -c core.quotePath=false status --porcelain 2>/dev/null)" || CH=""
+  if [ -n "$CH" ]; then
+    n=0; names=""
+    while IFS= read -r l; do n=$((n+1)); [ "$n" -le 5 ] && names="${names:+$names, }${l:3}"; done <<< "$CH"
+    LINES+=("$n uncommitted file(s): $names$([ "$n" -gt 5 ] && printf ', and %d more' $((n-5)))")
+  else LINES+=("nothing uncommitted"); fi
+fi
+if [ -f "$LIB/gate-log.sh" ]; then
+  . "$LIB/gate-log.sh"; crew_gate_log_read
+  if [ -n "${_CREW_GL:-}" ] && [ -f "$_CREW_GL" ]; then
+    last=""; while IFS= read -r l; do case "$l" in BLOCK$'\t'*) last="$l" ;; esac; done < "$_CREW_GL"
+    if [ -n "$last" ]; then IFS=$'\t' read -r _ rule why _ <<< "$last"; LINES+=("the last refusal in the gate log: ${rule} ${why:0:120}"); fi
+  fi
+fi
+fnd=""
+for f in .crewforth/*.json; do
+  [ -f "$f" ] || continue
+  c=0; while IFS= read -r l; do case "$l" in *'"rule": '*) c=$((c+1)) ;; esac; done < "$f"
+  [ "$c" -gt 0 ] && { b="${f##*/}"; fnd="${fnd:+$fnd, }${b%.json} $c"; }
+done
+[ -n "$fnd" ] && LINES+=("findings on record: $fnd")
+[ -s docs/SESSION_STATE.md ] && LINES+=("a handover is at docs/SESSION_STATE.md")
+[ "${#LINES[@]}" -gt 0 ] || exit 0
+
+SUM=""; for l in "${LINES[@]}"; do SUM="${SUM:+$SUM; }$l"; done
+SUM="${SUM:0:1800}"
+
+# ---- where it goes ----
+if [ -n "$GD" ] && [ -d "$GD" ]; then OUT="$GD/crewforth-session-snapshot.json"
+else mkdir -p .claude/state 2>/dev/null || exit 0; OUT=".claude/state/session-snapshot.json"; fi
+if [ "${BASH_VERSINFO[0]}" -ge 5 ] || { [ "${BASH_VERSINFO[0]}" -eq 4 ] && [ "${BASH_VERSINFO[1]}" -ge 2 ]; }; then printf -v NOW '%(%Y-%m-%dT%H:%M:%SZ)T' -1; else NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"; fi
+ESC="$(printf '%s\n' "$SUM" | LC_ALL=C awk -f "$LIB/json-string.awk" 2>/dev/null)" || exit 0
+printf '{"session_id":"%s","trigger":"%s","at":"%s","summary":"%s"}\n' "$SID" "${TRIG//[!a-z]/}" "$NOW" "$ESC" > "$OUT.$$" 2>/dev/null && mv -f "$OUT.$$" "$OUT" 2>/dev/null
+rm -f "$OUT.$$" 2>/dev/null
+exit 0

package/kit/hooks/prompt-approval.sh

@@ -514,6 +514,27 @@ _crew_prh_scan(){  # -> 0 when a PermissionRequest hook may be wired; _PRH names
   return "$r"
 }
 
+# ---- IS THE QUESTION OPEN HERE? One answer for every hook that offers it ------------------------------------------
+# guard-bash.sh offers it in a refusal; agent-outcome.sh offers it when crew-commit-agent is called in `auto`, so the
+# click is on offer before any commit is tried (B-2, a real session: with the refusal as the only way to it, a session
+# that asked for /crew-approve first never showed it). The text the user is asked stays _CREW_Q_JSON, here only.
+_CREW_Q_HERE="${BASH_SOURCE[0]%/*}"; [ "$_CREW_Q_HERE" = "${BASH_SOURCE[0]}" ] && _CREW_Q_HERE=.
+_crew_q_wired(){  # 0 = a settings file wires both halves on AskUserQuestion (guard-question.sh, then this file)
+  local f t d="${CLAUDE_PROJECT_DIR:-.}"
+  d="${d//\\//}"; d="${d%/}"
+  for f in "${CLAUDE_PLUGIN_ROOT:+${CLAUDE_PLUGIN_ROOT//\\//}/hooks/hooks.json}" "$d/.claude/settings.json" "$d/.claude/settings.local.json" "${HOME:+${HOME//\\//}/.claude/settings.json}"; do
+    [ -n "$f" ] && [ -f "$f" ] || continue
+    t=""; IFS= read -r -d '' t < "$f" || true
+    case "$t" in *'"PreToolUse"'*AskUserQuestion*guard-question.sh*'"PostToolUse"'*AskUserQuestion*prompt-approval.sh*) return 0 ;; esac
+  done
+  return 1
+}
+_crew_q_open(){  # $1 = permission mode -> 0 when the click may be offered: auto, both halves wired and beside this file, no PermissionRequest hook
+  [ "$1" = auto ] && [ -f "$_CREW_Q_HERE/guard-question.sh" ] && _crew_q_wired && ! _crew_prh_scan
+}
+# What the session is told to do, the same words wherever it is offered.
+_CREW_Q_ASK='ASK THE USER WITH ONE CLICK (stage first: the approval covers what is staged at that moment): show the commit message whole, in ONE code block, then call AskUserQuestion with exactly this input, nothing added or changed:'
+
 # ---- the approval question's context, and its PreToolUse half -----------------------------------------------
 # Shared by prompt-approval.sh (PostToolUse: it records the answer) and guard-question.sh (PreToolUse: it asks). The
 # PreToolUse half is a GATE and lives in a gate's file, so an error of its own refuses the call (CREW-FAILCLOSED)

package/kit/hooks/session-rehydrate.sh

@@ -68,11 +68,34 @@ if [ -f "$ROOT/.claude/hooks/pre-commit" ] && git -C "$ROOT" rev-parse --git-dir
   esac
 fi
 [ -n "$HOOKMSG" ] && MSG="${MSG:+$MSG }$HOOKMSG"
-[ -n "$MSG" ] || exit 0   # no handover to offer and nothing to say about language -> stay silent
+
+# THE STATE BEFORE THE COMPACTION. precompact-snapshot.sh wrote it just before this context was compacted: the
+# branch, the uncommitted files, the last gate refusal, the findings on record. Read back only after a compaction and
+# only into the session that wrote it (same session id); its summary is already JSON-escaped, so it is put into the
+# output as it is, and the rest of MSG stays fixed text that needs no escaping and no extra process.
+SNAP=""
+_rh="${BASH_SOURCE%[/\\]*}"; [ "$_rh" = "${BASH_SOURCE}" ] && _rh=.
+if [ "$SRC" = compact ] && [ -f "$_rh/../eval/lib/gate-log.sh" ]; then
+  . "$_rh/../eval/lib/gate-log.sh"
+  _sf=""
+  if crew_git_dir "$ROOT" && [ -f "$_CREW_GD/crewforth-session-snapshot.json" ]; then _sf="$_CREW_GD/crewforth-session-snapshot.json"
+  elif [ -f "$ROOT/.claude/state/session-snapshot.json" ]; then _sf="$ROOT/.claude/state/session-snapshot.json"; fi
+  _sid(){ _SID=""; local v="${1#*\"session_id\"}"; [ "$v" = "$1" ] && return 0; v="${v#*\"}"; _SID="${v%%\"*}"; }
+  if [ -n "$_sf" ] && IFS= read -r _sj < "$_sf" 2>/dev/null; then
+    _sid "$IN"; _mine="$_SID"; _sid "$_sj"
+    case "$_sj" in *'"summary":"'*)
+      if [ -n "$_mine" ] && [ "$_mine" = "$_SID" ]; then
+        _sum="${_sj#*\"summary\":\"}"; _sum="${_sum%\"\}*}"
+        SNAP="Before this context was compacted, Crewforth wrote down the state of the work from the files and the gates: $_sum. It is a record of that moment; check the files before relying on it."
+      fi ;;
+    esac
+  fi
+fi
+[ -n "$MSG$SNAP" ] || exit 0   # nothing to offer -> stay silent
 
 # hookSpecificOutput.additionalContext is the documented channel that injects text into the model's context.
 # ONE PATH, no jq: MSG is built from fixed constants 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"
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s%s%s"}}\n' "$MSG" "${MSG:+${SNAP:+ }}" "$SNAP"
 exit 0

package/kit/hooks/trace-blocklist.txt

@@ -12,6 +12,15 @@
 
 Co-Authored-By
 #test: Co-Authored-By: An Assistant <noreply@example.com>
+# The session-link trailer Claude Code asks the model to end a commit message with: it reached six pushed commits of a
+# project with Crewforth installed (2026-10-18), because nothing here named it. The trailer and the address are both
+# caught, so a message that keeps only one of them is still stopped. One line, not two: each line is one grep on every
+# commit (a process, 62-135 ms on Git Bash).
+Claude-Session:|claude\.ai/code/session_
+#test: Claude-Session: https://claude.ai/code/session_0123456789abcdef
+#test: see https://claude.ai/code/session_0123456789abcdef for the run
+#test-clean: the claude session limit is reached
+#test-clean: https://claude.ai/code is the web app
 # "Generated by/with" alone matched every machine-written header in existence — a pubspec.lock, an EF Core
 # scaffold, protoc, openapi-generator. A live --dotnet install could not make its FIRST commit because the
 # cloned base carries a Dart lockfile saying "Generated by pub". §4.1 is about AI AUTHORSHIP, so the pattern

package/kit/settings.json

@@ -216,6 +216,18 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/precompact-snapshot.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "matcher": "startup|resume|clear|compact|fork",

package/kit/skills/crew-code-review/SKILL.md

@@ -17,6 +17,21 @@ Trigger phrases: "code-review", "review the code", "review the PR", "review my c
 A review runs in four steps — **group, plan, review, fact-check** — and reports few findings that are right rather
 than many that might be. Every step below says what it produces.
 
+## 0. The pre-pass first, and the findings in one shape
+Before reading the diff, run the deterministic pre-pass (`eval/lib/review-prepass/` in either edition):
+`bash <dir>/prepass.sh` for the staged change, `--base <ref>` for a branch. It writes
+`.crewforth/review-prepass.json`: secret patterns, a debug call or TODO left in code, shellcheck on shell files, a
+lock file that moved without its manifest, a very large change. **Carry those over, do not re-derive them**; your
+time goes to what a pattern cannot see. rc 3 (no Node) or a `notMeasured` line means that part was NOT checked:
+say so in the review, never read it as clean.
+
+Write your own findings in the same shape (`crewforth.findings/1`: `rule` `review-<category>`, `severity`,
+`confidence`, `evidence` with `file`, `line` and a `text` quote, `detail` = what to do instead) and store them with
+`bash <dir>/../findings/findings.sh write review <file>`. A `critical` or `high` finding first goes to
+**crew-refuter** (claim + `file:line`, one call per lens, in parallel) and the document is written with
+`--verified`, which then refuses any `medium`-or-higher finding without its verifiers. This is model discipline:
+no hook runs the pre-pass or reads `review.json`.
+
 ## 1. Scope
 - **Review the lines this change adds or edits.** Deleted code is context for understanding them, not a target.
 - Code that is correct, or that the change did not touch, gets no comment.
@@ -142,6 +157,7 @@ five questions that decide *answer in the thread* vs *edit the code*: **`referen
 item leaves with a disposition from the triage table above — a reasoned refusal is an answer, silence is not.
 
 ## DoD (this skill's contribution)
+- The pre-pass ran (or its rc 3 / `notMeasured` is reported as unchecked), and the findings are in `.crewforth/review.json`.
 - The plan (what changed, the risks) came before the findings; every file in each group was read.
 - Every finding has a severity, a category and a reason, in the finding format above.
 - Scope creep and hidden complexity are flagged.