crewforth 3.4.0 → 3.5.0-rc.1

package/kit/hooks/map-stale.sh

@@ -0,0 +1,437 @@
+#!/usr/bin/env bash
+# map-stale.sh - says, once per agent, that the Crew Map was scanned before an edit to a file it cites, and which of
+# the project's own rules (.crewforth/contracts.md) live in the edited file; at Stop, tells the user which rules the
+# session's edits touched.
+#
+# WHY. .crewforth/crew-map.json describes modules from lines the scan read. Its module facts are true of the tree
+# it was scanned from; after an edit to a cited file they may not be. A planner that reads a stale map plans
+# against code that has moved. `crew-map.sh --check` can tell, but only when someone thinks to run it; this hook
+# says, at the moment it becomes true, that the question is now open.
+#
+# WIRING (settings.json / hooks.json): PostToolUse, matcher Edit|Write|MultiEdit|NotebookEdit; and Stop.
+#
+# FIRES when ALL of these hold: .crewforth/crew-map.json exists in the project; the edited file is inside the
+# project; the map cites that file (a `"file"` or `"manifest"` value); and this session and agent have not been
+# told yet. Then one line of additionalContext, and a marker so the same agent is not told again. A subagent
+# (`agent_id`) is told on its own: it did not see what the main session was told.
+#
+# CONTRACTS. When .crewforth/contracts.md cites the edited file (`- path:symbol` under a `## key`), the rules that
+# live there are added to the same note, each key once per session and agent, and the key joins the session's list.
+# At Stop, keys on that list the user has not been told yet go to the user as one systemMessage; a session that
+# touched no rule is silent. Both the agent's and the user's text are facts: a rule that still holds needs no edit.
+#
+# WORDING. A fact, not an order: what happened and which command answers it. Measured elsewhere in Crewforth and in
+# the hook-wording lessons it adopted: an imperative in a PostToolUse note is read as a task and derails the turn;
+# a fact is weighed. (UserPromptSubmit is the opposite case; route-hint.sh keeps its instruction wording.)
+#
+# MODES (CREW_MAP_STALE): unset / on  as above · off  nothing runs and no marker is written.
+#
+# NOT A GATE. It never blocks and never asks: every path out is exit 0, and a failure of its own is silence.
+#
+# COST. It runs after every Edit and Write call and at every Stop. A call that does not fire starts no process: the payload and the
+# map are read with the builtin `read`, the match is a `case`, the marker is a redirection. The first firing in a
+# project may pay one `mkdir`.
+MS_NOTE="Crew Map: .crewforth/crew-map.json cites lines in this file and was scanned before this edit, so its facts about the module may no longer hold. crew-map.sh --check (the scanner /crew-map runs) says whether the map still matches the tree, and the user can type /crew-map to rescan it. (Said once per agent.)"
+case "${CREW_MAP_STALE:-on}" in off|OFF|0|false) exit 0 ;; esac
+export LC_ALL=C
+trap 'exit 0' EXIT
+IFS= read -r -d '' INPUT || true
+INPUT="${INPUT:0:65536}"
+
+# ---- CREW-JSON-PARSE ------------------------------------------------------------------------------------
+_json_find(){  # $1 = text, $2 = a literal -> _JF = the offset of its first occurrence, -1 when there is none
+  # `${text%%"$literal"*}` gives the same offset and costs the DISTANCE to the occurrence times the length of the
+  # text (bash measures the remaining string at every position it tries), so with no occurrence at all it is the
+  # square of the size. That was the whole cost of a large Write: the path key is found near the front, and the
+  # look for a SECOND one then ran over the content -- measured on macOS, 1 MB: 9.6 s for each of the two key
+  # counts, against 0.02 s for one `case`; a 6 MB Write to a gate file was refused after 636 s, past the 600 s
+  # timeout, which means not refused. Here the text is walked a piece at a time, each piece long enough to hold an
+  # occurrence that starts in it, and the expansion only ever runs inside a piece that `case` says holds one.
+  # Two sizes of piece, because taking a piece out of the text costs the length of the text as well: a block is
+  # taken from the whole text, and the small pieces from the block.
+  local LC_ALL=C
+  local i=0 j n=${#1} kl=${#2} B=262144 C=4096 b bn c pre
+  _JF=-1
+  while [ "$i" -lt "$n" ]; do
+    b="${1:i:B+kl-1}"
+    case "$b" in *"$2"*)
+      j=0; bn=${#b}
+      while [ "$j" -lt "$bn" ]; do
+        c="${b:j:C+kl-1}"
+        case "$c" in *"$2"*) pre="${c%%"$2"*}"; _JF=$((i+j+${#pre})); return 0 ;; esac
+        j=$((j+C))
+      done ;;
+    esac
+    i=$((i+B))
+  done
+}
+_json_slice(){  # $1 = whole payload, $2 = key -> the raw (still JSON-escaped) string value, "" if absent
+  local LC_ALL=C   # FIRST, so every expansion below -- the key search included -- counts and cuts in bytes.
+                   # Lengths from ${#x} are used as offsets into ${y:n}; with the locale set before any of
+                   # them, the two never disagree about a unit. Walking bytes is safe because no UTF-8
+                   # continuation byte can be 0x5C or 0x22, so a cut cannot land inside a character at a
+                   # quote or backslash edge. What this line is worth in SPEED depends on the platform --
+                   # read the table in _json_unescape below before quoting a number for it.
+  local pre rest seg w r n base=0 j=0 cl lim run=0 chunk C=4096 W=256 hay="$1" k="\"$2\""; local -a acc=("")
+  # It ALSO sets `_JS`, so a caller on the hot path can read the value without `$( )`, which is a fork. The
+  # printf stays because the existing callers compose it (`_json_unescape "$(_json_slice …)"`), but the one
+  # caller that used to do its own fork-free extraction — `_CWD` — reads `_JS` and keeps costing nothing.
+  _JS=""
+  # Every "step past X" here is arithmetic on a length, never `${s#"$literal"}`. That shape reads like a
+  # constant-time strip and is not one: bash retries the pattern at every prefix length, so stripping an
+  # n-byte literal costs O(n^2). It was in this function twice, and both were measured:
+  #   * `${1#*"$2"}` found the key -- cheap when the key sits near the front, quadratic in the distance to it
+  #     otherwise. `permission_mode` behind a 100 KB command took 7.94s on Git Bash, 0.27s in front of it.
+  #     Captured from Claude Code 2.1.267, the real order puts `permission_mode` BEFORE `tool_input`, so on
+  #     that version this cost was not reachable -- this file's header had shown the opposite order, and was
+  #     wrong. The parse stays order-independent regardless: the order is not a documented contract, and the
+  #     payload is still moving (`effort` is absent from the field list recorded on 2.1.246).
+  #   * `${tail#"$seg"\"}` stepped past each escaped quote: 16.8s for a single 100 KB step on Git Bash,
+  #     against 0.002s for `${tail:${#seg}+1}` doing exactly the same thing.
+  # _json_find gives the FIRST occurrence. THAT ALONE IS NOT ENOUGH, and the sentence that used to stand here said it was: it claimed a
+  # command "containing the literal text `\"command\":\"` still cannot relocate the parse", which is true of
+  # that byte sequence and irrelevant, because this search is for `"command"` WITHOUT the colon. A JSON VALUE
+  # equal to the key name is exactly those bytes between two unescaped quotes. Measured on the shipped hook:
+  #   {"tool_name":"Bash","a":"command","ls":1,"tool_input":{"command":"rm -rf /"}}   ->  read `ls`
+  #   {"a":"permission_mode","default":1,"permission_mode":"bypassPermissions",…}     ->  read `default`
+  #   {"a":"file_path","/tmp/ok":1,"tool_input":{"file_path":".claude/hooks/x.sh"}}   ->  read `/tmp/ok`
+  # In each case the gate judged a harmless string while a dangerous one was the actual argument, and jq read
+  # the real value -- so on a stock Windows desktop, where this was already the only parser, the gate could be
+  # aimed with one extra key. The loop below therefore accepts an occurrence only when optional JSON whitespace
+  # and then `:` follow it, which is the only place a key can appear; everything else keeps searching.
+  # Stepping by length removed the quadratic strip, but each escaped quote still sliced and re-assigned the
+  # whole remainder, so an escape-dense command stayed k*n here as well (2.2s of the 6.8s described in
+  # _json_unescape below, on Git Bash). The walk is chunked the same way: the payload is read 4096 bytes at a
+  # time and every per-quote operation stays inside the chunk. One thing is carried across edges on purpose
+  # -- the length of the backslash run in front of a quote -- because that run can straddle a window or a
+  # chunk, and its parity is what decides whether the quote ends the value. Isolated, escape-dense 44030 B:
+  # 2.61s -> 0.41s on Git Bash 5.3.15, 0.93s -> 0.09s on macOS/bash 3.2.
+  # Output is byte-identical to the previous shape across 378 cases at four chunk/window sizes down to 7 and 1
+  # bytes, and that shape to the one before it across a 27-case battery (escaped quotes, backslash runs before
+  # a quote, the key twice, the key appearing first as a value, glob metacharacters, UTF-8, no closing quote,
+  # empty input). Broken twins -- the run not carried across a window, a byte skipped after a quote -- prove
+  # the battery sees both.
+  # THE NUMBER OF PASSES IS CAPPED, for the same reason guard-write caps the path length: an unbounded cost on
+  # a PreToolUse hook is a gate with an off switch, because a hook killed at its timeout emits no exit 2.
+  # Each decoy costs one more `%%` scan over the remainder, so the work is quadratic in the number of decoys.
+  # Measured on macOS/bash, single call, `"k<i>":"command"` decoys in front of the real key:
+  #      50 decoys    844 B    12 ms        800 decoys   13544 B    126 ms
+  #     200 decoys   3344 B    19 ms       3200 decoys   56544 B   1839 ms
+  # Git Bash's parameter expansion is several times slower again, so the tail is where the timeout lives. A
+  # real payload carries ZERO decoys -- 64 is far above anything a producer can legitimately emit -- and going
+  # over the cap is reported SEPARATELY (`_KC_CAPPED`), not as a large count, so the caller can refuse with a
+  # reason the reader can act on instead of a sentinel dressed up as a measurement. Fail-closed either way.
+  # THE COST IS ONE THIS CHANGE INTRODUCES, and it is worth saying so plainly rather than implying the cap
+  # protects something pre-existing: before the colon requirement the scan STOPPED at the first occurrence, so
+  # decoys cost essentially nothing (measured on stock Windows: 0 decoys 0.18 ms, 3200 decoys 1.60 ms per call,
+  # roughly linear) -- and it read the decoy, which is the hole. The cap is load-bearing for the new cost, so
+  # raising or removing it later is not a tidy-up.
+  # The bound is on the LOOP, not on the payload, so an ordinary command pays nothing: the same 56572 B flood
+  # is refused in 93-94 ms with jq/python3 present and 168-169 ms on the slice path this paragraph is about,
+  # both far inside the 60s timeout these hooks had when this was measured, while a 46 KB legitimate command is 325 ms on macOS -- a figure that
+  # predates this change and belongs to the walk, not to the cap.
+  local _cap=64 _seen=0
+  while :; do
+    _json_find "$hay" "$k"                     # where the next `"key"` starts
+    [ "$_JF" -ge 0 ] || return 0               # no further occurrence: emit nothing
+    _seen=$((_seen+1)); [ "$_seen" -le "$_cap" ] || return 0
+    rest="${hay:_JF+${#k}}"                    # past `"key"`
+    while [ -n "$rest" ] && [[ "${rest:0:1}" == [$' \t\n\r'] ]]; do rest="${rest:1}"; done
+    case "$rest" in
+      :*) rest="${rest:1}"; break ;;           # whitespace then `:` -- this occurrence IS the key
+      *)  hay="$rest" ;;                       # a value, or another token: keep looking
+    esac
+  done
+  # THE VALUE MUST BE A STRING. `"command":123}}` used to come back as the literal text `:123}}` -- the old
+  # shape skipped forward to the next quote wherever it was, so a non-string value handed the matchers the
+  # payload's own punctuation to judge. Emitting nothing instead lets the caller's "no readable command"
+  # refusal fire, which is the honest answer for a value these gates cannot read.
+  while [ -n "$rest" ] && [[ "${rest:0:1}" == [$' \t\n\r'] ]]; do rest="${rest:1}"; done
+  case "$rest" in '"'*) rest="${rest:1}" ;; *) return 0 ;; esac
+  # Walk to the closing quote that is NOT escaped. A `"` preceded by an odd number of backslashes is content.
+  n=${#rest}; chunk="${rest:0:C}"; cl=${#chunk}
+  while :; do
+    lim=$((cl - j))
+    if [ "$lim" -le 0 ]; then
+      [ $((base + cl)) -lt "$n" ] || break                 # no closing quote at all: everything is already taken
+      base=$((base + j)); chunk="${rest:base:C}"; cl=${#chunk}; j=0; continue
+    fi
+    [ "$lim" -le "$W" ] || lim=$W
+    w="${chunk:j:lim}"
+    seg="${w%%\"*}"
+    if [ "$seg" = "$w" ]; then                             # no quote in view: take all of it, carry the run
+      acc+=("$w"); j=$((j+lim))
+      r="${w##*[!\\]}"; case "$w" in *[!\\]*) run=${#r} ;; *) run=$((run+${#w})) ;; esac
+      continue
+    fi
+    acc+=("$seg"); j=$((j+${#seg}+1))
+    r="${seg##*[!\\]}"; case "$seg" in *[!\\]*) run=${#r} ;; *) run=$((run+${#seg})) ;; esac
+    if [ $((run % 2)) -eq 1 ]; then acc+=("\""); run=0; else break; fi
+  done
+  local IFS=''; _JS="${acc[*]}"; printf '%s' "$_JS"
+}
+_json_unescape(){  # left-to-right, a chunk at a time; a two-pass sed would corrupt `\\"` (escaped backslash + quote)
+  # This is the tier-3 path below -- the one a stock Windows install actually runs on. It used to walk ONE
+  # CHARACTER at a time, which is O(n^2) twice over: `${s%"${s#?}"}` matches a pattern the length of the
+  # entire remainder just to read one character, and `out="$out$c"` recopies the output for each one.
+  #
+  # That was not a comfort question. This hook's timeout was 60s then -- set in settings.json (600s since 3.1.0), NOT Claude Code's
+  # default, and reading the default instead is how a first pass at this got the consequence wrong. A
+  # PreToolUse hook KILLED at its timeout emits no exit 2, so every rule below is simply skipped. Measured on
+  # the tier-3 path with jq and python3 both shadowed, the old shape crossed 60s at ~4.3 KB. And 4.3 KB is
+  # not exotic: across 6791 Bash calls in 280 real transcripts, 2.49% of commands are bigger, and the largest
+  # is 46815 B, which the old shape needed roughly 39 minutes to decode. One Bash call in forty walked past
+  # §4.4 and §4.5 entirely, silently, on every stock Windows desktop.
+  #
+  # Two changes, and their wins are NOT the same shape -- writing them down as one number was the mistake
+  # this comment exists to avoid repeating:
+  #   * Taking the whole run up to the next backslash in ONE expansion, and indexing with `${s:0:1}` instead
+  #     of matching a pattern, is 47x on a 4.4 KB payload. This one holds on every machine.
+  #   * `local LC_ALL=C` makes these expansions byte-oriented instead of re-decoding the string on every
+  #     substring operation. What that is WORTH depends on the platform, and putting a single number here
+  #     would have been wrong three separate ways -- it was written as "another 5x" twice before this:
+  #         macOS / bash 3.2, a locale set .................. 5x
+  #         Git Bash 5.3.15, a locale set ................... 1.23x   (measured on the OLD shape; the new one
+  #                                                                    touches the locale once per escape
+  #                                                                    rather than once per character, so its
+  #                                                                    ratio is smaller and unmeasured)
+  #         Git Bash, LANG empty -- what Claude Code starts .. nothing at all
+  #     So speed is not what keeps this line; CORRECTNESS is, and that half holds everywhere. `[0-9a-fA-F]`
+  #     below is a collation-defined range outside the C locale: on a tr_TR desktop it is not 0-9a-f. That
+  #     alone would justify the line, and it costs nothing. `local` restores the previous locale on return
+  #     -- verified on bash 3.2 and on Git Bash 5.3.15, not assumed.
+  #
+  # Then the cost moved rather than went away. With the per-character walk gone, each escape still sliced the
+  # whole REMAINDER -- `s="${s:${#pre}+1}"` -- so an escape-dense command stayed k*n: on Git Bash a 44080 B
+  # command with 2755 escapes took 6.8s, 11% of the timeout. The input is now touched only a chunk at a time
+  # (`${s:base:C}`, once per 4096 bytes) and every per-escape operation stays inside that chunk, so no escape
+  # pays for the length of the whole command. That is the change that matters: bounding only the lookahead,
+  # while still indexing the full string, was measured too and gave about 4x on both machines, against 6-12x
+  # for the chunked walk. Five bytes are held back at a chunk's end whenever more input follows, so a
+  # `\uXXXX` that starts in a chunk ends in it.
+  # The output goes into an array joined once, not a string recopied at every append, and `\n`/`\t` are
+  # written `$'\n'`/`$'\t'`, so this file carries no raw TAB for an editor or a copy to turn into spaces.
+  #
+  # Measured, isolated, previous shape -> this one:
+  #     macOS/bash 3.2   escape-dense 44030 B, 2590 escapes .. 1.44s -> 0.12s
+  #                      sparse 100014 B, 4 escapes ........... 0.09s -> 0.02s
+  #     Git Bash 5.3.15  escape-dense 44030 B, 2590 escapes .. 3.92s -> 0.54s
+  #     (LANG empty)     sparse 99997 B, 4 escapes ............ 0.49s -> 0.07s
+  # These numbers do not travel, which is why each one names its machine.
+  #
+  # Output is byte-identical to the previous shape across 478 cases, each run at four chunk/window sizes
+  # down to 7 and 1 bytes so that an edge falls every few bytes; that shape was itself byte-identical to
+  # the original character walk across a 31-case battery (escaped quotes, `\\`, a lone trailing backslash, a
+  # truncated `\u`, Turkish, emoji). Deliberately broken twins -- the 5-byte margin cut to 4, the backslash
+  # not stepped over -- prove the battery sees both edges, and tier 1 and tier 3 return the same verdict on
+  # the gate cases.
+  local LC_ALL=C
+  local s="$1" pre w c h n base=0 j=0 cl lim chunk C=4096 W=256; local -a acc=("")
+  case "$s" in *\\*) ;; *) _JU="$s"; printf '%s' "$s"; return 0 ;; esac   # no escapes: the common case pays nothing
+  n=${#s}; chunk="${s:0:C}"; cl=${#chunk}
+  while :; do
+    lim=$((cl - j))
+    if [ $((base + cl)) -lt "$n" ]; then                  # more input after this chunk: hold 5 bytes back, so
+      lim=$((lim - 5))                                     # a `\uXXXX` that starts in a chunk also ends in it
+      if [ "$lim" -le 0 ]; then base=$((base + j)); chunk="${s:base:C}"; cl=${#chunk}; j=0; continue; fi
+    else
+      [ "$lim" -gt 0 ] || break
+    fi
+    [ "$lim" -le "$W" ] || lim=$W
+    w="${chunk:j:lim}"
+    pre="${w%%\\*}"                                        # the literal run before the next backslash in view
+    if [ "$pre" = "$w" ]; then acc+=("$w"); j=$((j+lim)); continue; fi
+    acc+=("$pre"); j=$((j+${#pre}+1))
+    if [ $((base + j)) -ge "$n" ]; then acc+=("\\"); break; fi   # a lone trailing backslash stays literal, as before
+    c="${chunk:j:1}"; j=$((j+1))
+    case "$c" in
+      n) acc+=($'\n') ;;
+      t) acc+=($'\t') ;;
+      r) ;;
+      b|f) acc+=(" ") ;;
+      u) if [ $((n - base - j)) -ge 4 ]; then h="${chunk:j:4}"; j=$((j+4)); else h=""; fi   # a short tail is left alone, as before
+         # A `\uXXXX` used to become a literal `?`. That is not a lossy nicety, it is a hole: `\u002e` is `.`,
+         # so `\u002eclaude/hooks/guard-bash.sh` decoded to `?claude/…` and matched no gate pattern, while jq
+         # decoded the same bytes to the real path — the two tiers disagreed on whether a payload was an
+         # attack. Printable ASCII is decoded properly (builtin printf, no fork); anything else still becomes
+         # `?`, which is only ever a display concern because this value is used for MATCHING, never to write.
+         case "$h" in
+           00[2-7][0-9a-fA-F]) printf -v c "\\x${h#00}"; acc+=("$c") ;;
+           # The three dashes PowerShell accepts in front of a parameter name, as themselves: as `?` they hid
+           # `\u2013Recurse \u2013Force` from the delete rule, while the same bytes sent raw were caught.
+           2013) acc+=("–") ;; 2014) acc+=("—") ;; 2015) acc+=("―") ;;
+           *)                  acc+=("?") ;;
+         esac ;;
+      *) acc+=("$c") ;;
+    esac
+  done
+  # ALSO sets `_JU`, for the same reason `_json_slice` sets `_JS`: a caller on the hot path reads the value from it
+  # and sends this printf to /dev/null, instead of paying a `$( )` — a fork — on every tool call.
+  local IFS=''; _JU="${acc[*]}"; printf '%s' "$_JU"
+}
+_json_keycount(){  # $1 = payload, $2 = key -> sets _KC to how many times it occurs AS A KEY
+  # IT SETS A VARIABLE INSTEAD OF PRINTING, and that is not a style choice. Written as `n="$(_json_keycount
+  # …)"` first, which is a command substitution, which is a FORK -- on a hook that runs before every Bash and
+  # every Write call. Measured on macOS/bash, typical payload, 200 reps: the substitution form cost 0.790 ms
+  # per call against 0.090 ms for the raw byte test it replaces, and the whole hook went 15.00 -> 16.58 ms.
+  # This project's own recorded Git Bash process cost is 62-135 ms, rising to ~400 ms under load, so three
+  # added forks per call would have been a freeze on the platform the change is meant to protect. Setting _KC
+  # keeps the count in the caller's own shell: expansion only, zero forks.
+  # The counter the ambiguity refusals need, and it exists because the hand-written byte test they used to do
+  # looked for a DIFFERENT token than the parser above: `"key":` compact, while the parser searches `"key"` and
+  # tolerates whitespace before the colon. Two consequences, both measured on the shipped hook:
+  #   * `{…"meta":{"command":"ls"},"tool_input":{"command" : "rm -rf /"}}` -- ONE SPACE and the duplicate-key
+  #     refusal went blind while the parser happily read the first value.
+  #   * a key name appearing as a VALUE was counted as an occurrence by neither, which is the hole the parser
+  #     above now closes; counting the same form here is what keeps the two from drifting apart again.
+  # Sharing ONE definition with the parser is the point: a guard that searches for something else than the
+  # thing it guards is the defect, not an implementation detail.
+  # WHAT THE TOKEN CAN BE, stated correctly. An earlier version of this comment said the bytes `"command"`
+  # with both quotes unescaped "can only be a key or a value equal to the key name". That is wrong, and the
+  # counter-example was found by review, not by reasoning: a KEY whose own name ends with a quote spells the
+  # token out of its escaped quote plus the string's terminator --
+  #   {"tool_input":{"x\"command":"DECOY","command":"rm -rf /"}}   slice -> DECOY, count -> 2
+  # which is refused BECAUSE the count sees two, not because the invariant held. The same shape as a VALUE is
+  # harmless (a string's terminator is followed by `,` `}` `]`, never `:`, so it is skipped and not counted:
+  #   {"description":"ends with \"command","command":"rm -rf /"}    slice -> rm -rf /, count -> 1 ).
+  # What IS true, and is what keeps ordinary work from being refused: content can contribute at most one
+  # occurrence per string and only as that string's tail, where the next byte is never a colon. Measured on 19
+  # payloads built by a real JSON encoder -- `grep -rn '"command":' .`, a heredoc writing a hooks.json, `sed`
+  # over settings.json, a commit message quoting the word, commands ending in `"command` -- every count <= 1.
+  # Same pass cap as the slice, and over-cap reports AMBIGUOUS rather than a true count: the callers refuse on
+  # `> 1`, so a payload built to outrun the loop is refused instead of being timed out past the gate.
+  local LC_ALL=C hay="$1" k="\"$2\"" rest c=0 _cap=64 _seen=0
+  _KC=0; _KC_CAPPED=0
+  while :; do
+    _json_find "$hay" "$k"
+    [ "$_JF" -ge 0 ] || { _KC=$c; return 0; }
+    # OVER-CAP IS ITS OWN ANSWER, not a large count. `_KC_CAPPED` lets the caller say what actually happened:
+    # the occurrences it stopped at are candidate positions, key-form or not, so calling them "65 keys" was a
+    # sentinel dressed up as a measurement and the remedy it offered ("send one key") was already satisfied.
+    _seen=$((_seen+1)); [ "$_seen" -le "$_cap" ] || { _KC=$((_cap+1)); _KC_CAPPED=$_cap; return 0; }
+    rest="${hay:_JF+${#k}}"
+    while [ -n "$rest" ] && [[ "${rest:0:1}" == [$' \t\n\r'] ]]; do rest="${rest:1}"; done
+    case "$rest" in :*) c=$((c+1)) ;; esac
+    hay="$rest"
+  done
+}
+# ---- /CREW-JSON-PARSE -----------------------------------------------------------------------------------
+
+# ---- helpers: builtins only ------------------------------------------------------------------------------
+_ms_id(){  # $1 = raw id -> _MSI: letters, digits, _ and - only, 80 at most (it names a file)
+  _MSI="${1//[!A-Za-z0-9_-]/}"; _MSI="${_MSI:0:80}"; }
+_ms_path(){  # $1 = a path, JSON-escaped or not -> _MSP: forward slashes, a drive letter in lower case, no trailing /
+  local p="${1//\\\\/\\}" u=ABCDEFGHIJKLMNOPQRSTUVWXYZ l=abcdefghijklmnopqrstuvwxyz
+  p="${p//\\//}"
+  case "$p" in [A-Z]:/*) u="${u%%"${p:0:1}"*}"; p="${l:${#u}:1}${p:1}" ;; esac   # the drive letter, lower case, no fork
+  _MSP="${p%/}"; }
+
+# ---- the payload -----------------------------------------------------------------------------------------
+_json_slice "$INPUT" hook_event_name >/dev/null; EV="$_JS"
+case "$EV" in PostToolUse|Stop) ;; *) exit 0 ;; esac
+_json_slice "$INPUT" session_id >/dev/null; _ms_id "$_JS"; SID="$_MSI"; [ -n "$SID" ] || exit 0
+# The project: the hook is started in it (settings.json cds there); the plugin edition reads it from the env or the payload.
+P="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$P" ]; then _json_slice "$INPUT" cwd >/dev/null; P="$_JS"; fi
+[ -n "$P" ] || exit 0
+_ms_path "$P"; P="$_MSP"
+M="$P/.crewforth/crew-map.json"; C="$P/.crewforth/contracts.md"; ST="$P/.claude/state"
+
+# ---- Stop: the user hears which of the project's rules this session's edits touched, each key once ------------
+if [ "$EV" = Stop ]; then
+  S="$ST/contracts-$SID"
+  [ -f "$S" ] || exit 0
+  LIST=""; IFS= read -r -d '' LIST < "$S" || true
+  SAID=""; [ -f "$S-said" ] && { IFS= read -r -d '' SAID < "$S-said" || true; }
+  NEW=""; rest="$LIST"
+  while [ -n "$rest" ]; do
+    rest="${rest#|}"; k="${rest%%|*}"; rest="${rest#"$k"}"; rest="${rest#|}"
+    [ -n "$k" ] || continue
+    case "$SAID" in *"|$k|"*) ;; *) NEW="$NEW${NEW:+, }$k"; SAID="$SAID|$k|" ;; esac
+  done
+  [ -n "$NEW" ] || exit 0
+  printf '%s' "$SAID" > "$S-said" 2>/dev/null || exit 0
+  printf '{"systemMessage":"Contracts: this session edited files that .crewforth/contracts.md cites for %s. A review gives a verdict per key (the user can type /crew-review); a rule that still holds needs no change to the file."}\n' "$NEW"
+  exit 0
+fi
+
+_json_slice "$INPUT" tool_name >/dev/null
+case "$_JS" in Edit|Write|MultiEdit|NotebookEdit) ;; *) exit 0 ;; esac
+_json_slice "$INPUT" agent_id >/dev/null;   _ms_id "$_JS"; AG="$_MSI"
+[ -f "$M" ] || [ -f "$C" ] || exit 0
+
+_json_slice "$INPUT" file_path >/dev/null; FP="$_JS"
+[ -n "$FP" ] || { _json_slice "$INPUT" notebook_path >/dev/null; FP="$_JS"; }
+[ -n "$FP" ] || exit 0
+_ms_path "$FP"; FP="$_MSP"; PP="$P"
+# Git Bash may give the project as /c/... while the tool names the file C:\...: compare them in one form.
+case "$FP:$PP" in [a-z]:/*:/[A-Za-z]/*) _ms_path "${PP:1:1}:${PP:2}"; PP="$_MSP" ;; esac
+case "$FP" in
+  "$PP"/*) REL="${FP:${#PP}+1}" ;;
+  /*|[A-Za-z]:/*) exit 0 ;;          # outside the project: the map does not describe it
+  *) REL="${FP#./}" ;;               # relative: already the project's
+esac
+case "$REL" in ''|../*|*/../*) exit 0 ;; esac
+
+# Whatever is said below leaves through one line of JSON, written on the way out, so an early exit of the map's
+# part still delivers the contracts' part. The map's note comes first.
+MN=""; CN=""
+_ms_out(){ [ -n "$MN$CN" ] || return 0
+  printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s%s%s"}}\n' "$MN" "${MN:+${CN:+ }}" "$CN"; }
+trap '_ms_out; exit 0' EXIT
+
+# ---- the project's rules: .crewforth/contracts.md (eval/lib/crew-map/contracts.mjs) ------------------------
+# A section is `## key`, its rule (the first paragraph) and `- path:symbol` cites. An edit to a cited file brings
+# the rules that live there into the agent's context, each key once per session and agent; the session's list of
+# touched keys is what Stop tells the user. At most 1 MB of the file is read, line by line, with builtins only.
+if [ -f "$C" ]; then
+  CT=""; IFS= read -r -d '' -n 1048576 CT < "$C" || true
+  case "$CT" in *"$REL:"*)
+    TK="$ST/contracts-told-$SID${AG:+-$AG}"; TOLD=""; [ -f "$TK" ] && { IFS= read -r -d '' TOLD < "$TK" || true; }
+    SL="$ST/contracts-$SID"; LIST=""; [ -f "$SL" ] && { IFS= read -r -d '' LIST < "$SL" || true; }
+    key=""; rule=""; para=0; told0="$TOLD"; list0="$LIST"
+    while IFS= read -r l || [ -n "$l" ]; do
+      l="${l%$'\r'}"
+      case "$l" in "## "*) _ms_id "${l#"## "}"; key="$_MSI"; rule=""; para=1; continue ;; esac
+      [ -n "$key" ] || continue
+      t="${l#"${l%%[![:space:]]*}"}"
+      case "$t" in
+        "- $REL:"?*|"* $REL:"?*)
+          case "$LIST" in *"|$key|"*) ;; *) LIST="$LIST|$key|" ;; esac
+          case "$TOLD" in *"|$key|"*) ;; *)
+            TOLD="$TOLD|$key|"; r="${rule:0:300}"; r="${r//\\/\\\\}"; r="${r//\"/\\\"}"; r="${r//$'\t'/ }"
+            CN="$CN${CN:+ }$key: $r" ;;
+          esac ;;
+        "- "*|"* "*) para=2 ;;
+        '') [ "$para" = 3 ] && para=2 ;;
+        *) if [ "$para" = 1 ]; then rule="$t"; para=3; elif [ "$para" = 3 ]; then rule="$rule $t"; fi ;;
+      esac
+    done <<< "$CT"
+    if [ "$TOLD" != "$told0" ] || [ "$LIST" != "$list0" ]; then
+      [ -d "$ST" ] || mkdir -p "$ST" 2>/dev/null
+      printf '%s' "$TOLD" > "$TK" 2>/dev/null; printf '%s' "$LIST" > "$SL" 2>/dev/null
+    fi
+    [ -n "$CN" ] && CN="Contracts: .crewforth/contracts.md cites this file for these rules. $CN (Each rule said once per agent; a change that keeps a rule needs no edit to the file.)"
+  ;; esac
+fi
+
+# ---- the map ------------------------------------------------------------------------------------------------
+[ -f "$M" ] || exit 0
+MK="$ST/map-stale-$SID${AG:+-$AG}"
+[ -e "$MK" ] && exit 0
+
+# The map is written by the scanner's serializer: `"file": "<path>"`, one space after the colon, the path relative
+# and in forward slashes. The path is compared in that JSON form, so a quote or backslash in a name cannot widen it.
+J="${REL//\\/\\\\}"; J="${J//\"/\\\"}"
+# At most 4 MB of it is read: a map that large is a monorepo's, and a path cited past that point goes unsaid rather
+# than costing every edit the time to read the rest.
+MAPTXT=""; IFS= read -r -d '' -n 4194304 MAPTXT < "$M" || true
+case "$MAPTXT" in
+  *"\"file\": \"$J\""*|*"\"manifest\": \"$J\""*) ;;
+  *) exit 0 ;;
+esac
+
+[ -d "$ST" ] || mkdir -p "$ST" 2>/dev/null || exit 0
+: > "$MK" 2>/dev/null || exit 0
+MN="$MS_NOTE"
+exit 0

package/kit/hooks/pre-commit

@@ -236,20 +236,60 @@ FAL=""; [ -n "$GITROOT" ] && [ -f "$GITROOT/.floor-allowlist.txt" ] && FAL="$GIT
 # EXACT pattern line. `path:` is matched as a shell `case` pattern: `*` crosses `/` and `**` is not special, so
 # `path:*.cs` exempts every C# file in the tree. Documented in floor-blocklist.txt and pinned in smoke §7h2. The allowlist sits in the same diff as the code it excuses, which is the point: an exception
 # is a decision someone can see, not a rule that quietly got weaker.
+#
+# EVERY EXCEPTION SAYS WHY, on its own line: `<entry>  # <reason, at least 20 characters>`. A bare `rule:` line used to
+# switch a rule off for the whole repository with nothing a reviewer could weigh; now an entry without its reason
+# exempts nothing, and the commit names the line. The reason starts at the first " # " (space, hash, space), which no
+# floor pattern contains (they spell a literal hash as [#]).
+_fal_split(){ # $1 = allowlist line -> FAL_E (the entry) and FAL_R (the reason, trimmed; empty when there is none)
+  FAL_E="${1%% # *}"; FAL_R=""
+  [ "$FAL_E" != "$1" ] && FAL_R="${1#* # }"
+  FAL_E="${FAL_E%"${FAL_E##*[![:space:]]}"}"
+  FAL_R="${FAL_R#"${FAL_R%%[![:space:]]*}"}"; FAL_R="${FAL_R%"${FAL_R##*[![:space:]]}"}"
+}
+_FAL_SAID="|"
+_fal_unreasoned(){ # $1 = the bare line: reported once per commit, and the commit is stopped
+  case "$_FAL_SAID" in *"|$1|"*) return 0 ;; esac
+  _FAL_SAID="$_FAL_SAID$1|"
+  echo "FLOOR-ALLOWLIST: '$1' exempts nothing without a reason — write it as: $1  # <why, at least 20 characters>"
+  HIT=1
+}
 _floor_allowed(){ # $1 = rule, $2 = pattern (may be empty), $3 = path
   [ -n "$FAL" ] || return 1
-  local a
+  local a m
   while IFS= read -r a || [ -n "$a" ]; do
     a="${a%$'\r'}"
-    case "$a" in
-      ''|\#*) continue ;;
-      path:*) case "$3" in ${a#path:}) return 0 ;; esac ;;
-      rule:*) [ "${a#rule:}" = "$1" ] && return 0 ;;
-      *)      [ -n "$2" ] && [ "$a" = "$2" ] && return 0 ;;
+    case "$a" in ''|\#*) continue ;; esac
+    _fal_split "$a"; m=0
+    case "$FAL_E" in
+      path:*) case "$3" in ${FAL_E#path:}) m=1 ;; esac ;;
+      rule:*) [ "${FAL_E#rule:}" = "$1" ] && m=1 ;;
+      *)      [ -n "$2" ] && [ "$FAL_E" = "$2" ] && m=1 ;;
     esac
+    [ "$m" = 1 ] || continue
+    [ "${#FAL_R}" -ge 20 ] || _fal_unreasoned "$FAL_E"
+    return 0
   done < "$FAL"
   return 1
 }
+# A staged change to the allowlist itself is checked whole: every entry has a reason of 20+ characters, and no two
+# entries share one word for word (a copied reason explains neither). Only when the file is in this commit, so a
+# project whose old list has bare lines is not locked out of unrelated commits; those lines exempt nothing instead.
+if [ -n "$FAL" ] && ! git diff --cached --quiet -- "$FAL" 2>/dev/null; then
+  _fal_reasons="
+"
+  while IFS= read -r a || [ -n "$a" ]; do
+    a="${a%$'\r'}"
+    case "$a" in ''|\#*) continue ;; esac
+    _fal_split "$a"
+    if [ "${#FAL_R}" -lt 20 ]; then _fal_unreasoned "$FAL_E"; continue; fi
+    case "$_fal_reasons" in *"
+$FAL_R
+"*) echo "FLOOR-ALLOWLIST: '$FAL_E' repeats the reason of another entry word for word — say why THIS exception is needed"; HIT=1 ;; esac
+    _fal_reasons="$_fal_reasons$FAL_R
+"
+  done < "$FAL"
+fi
 
 # Test files, by the naming each ecosystem uses. Names and not whole `test/` directories, because deleting a
 # fixture or a helper there is not a test made easier. Rust integration tests are the one convention that is a
@@ -684,7 +724,8 @@ fi
 if [ "$HIT" -ne 0 ]; then
   echo "-----------------------------------------------------------"
   echo "Commit stopped. Remove the AI-authorship trace / vendor name / secret / bloated file / bar-lowering move from the staged changes."
-  echo "A bar-lowering move that is genuinely warranted? record it in .floor-allowlist.txt at the repo root (path:<glob>, rule:<name>, or the exact pattern line) — in the same commit, where review sees it. A path: glob's * also crosses directories: write the narrowest path."
+  echo "A bar-lowering move that is genuinely warranted? record it in .floor-allowlist.txt at the repo root (path:<glob>, rule:<name>, or the exact pattern line, each followed by '  # <reason, 20+ characters>') — in the same commit, where review sees it. A path: glob's * also crosses directories: write the narrowest path."
+  echo "Not the way out: an allowlist line written only to get this commit through. Fix the code; a rule: line switches a rule off for the whole repository and needs an ADR."
   echo "False positive (trace/secret)? add the EXACT pattern line to .trace-allowlist.txt or .secret-allowlist.txt at the repo root."
   echo "Private path flagged but genuinely public? add that exact term to .private-allowlist.txt at the repo root."
   echo "Large file is intentional? raise CREW_MAX_FILE_BYTES, use Git LFS, or gitignore the build/vendored path."