crewforth 3.1.0-rc.4 → 3.1.0-rc.5

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

@@ -0,0 +1,392 @@
+#!/usr/bin/env bash
+# guard-agent-model.sh - a crew agent is called with a model, and not below its floor.
+#
+# WHY. The model for a piece of work is chosen per call, by risk (the table in CLAUDE.md): haiku for mechanical
+# work, sonnet for ordinary work, opus where a mistake is expensive. Left to the session's default, every agent ran
+# on the session's model; left to a habit of "cheapest", an audit could run below the code it clears. Two things
+# are held here, at the tool level:
+#   * a call to a crew-* agent NAMES its model, so the choice is made and can be read in the transcript;
+#   * some agents have a floor: crew-security-expert runs on opus; crew-privacy-agent, crew-review-agent,
+#     crew-planner and crew-database-expert on sonnet or above.
+# It only refuses, with the reason and the model that is needed. It never rewrites a call. THE WORDING IS READ BY
+# ANOTHER PROGRAM (the Studio panel): a refusal is one line that begins `GUARD (agent model):`, and a floor is said
+# as ` runs on <model> or above`. The suite pins both. Measured on Claude Code
+# 2.1.294: refused this way, the session repeated the same call with the model named, and a call with
+# model: "haiku" ran its agent on Haiku (the agent's own transcript names the model).
+#
+# NOT TOUCHED: an agent that is not crew-* (Explore, general-purpose, a project's own), and any tool but Agent.
+# SWITCHES, read from the session's environment:
+#   CREW_MODEL_ROUTING=off   the gate does nothing, which is how it was before 3.1.0.
+#   CREW_ALLOW_FABLE=1       `fable` may be named; without it a call that names it is refused.
+# HONEST SCOPE: which model fits the TASK is the caller's judgement and nothing here reads the task. The model is
+# read from the call's own `model` field; an agent file's frontmatter is not read.
+set -uo pipefail
+# ---- CREW-LOCALE -----------------------------------------------------------------------------------------
+# Everything this gate matches with runs in the C locale, whatever the session's own is. Under a Turkish locale
+# the letters i and I are not each other's other case (their partners are İ and ı), and every case-insensitive
+# match here is written in ASCII. Measured under tr_TR.UTF-8 with the locale left as it came:
+#   GNU grep 3.11 / bash 5.2 on Linux: `grep -i init` does not find INIT (-F, -E and plain alike);
+#     bash's nocasematch does not match GIT against git; `[A-Za-z]` in a regex does not hold I; awk's tolower
+#     turns GIT into gıt. The suite, run whole under that locale, went from 4 failures to 30: a recursive
+#     Remove-Item, a write to a gate file, `git config --remove-section core`, a read of a nested .env and a
+#     staged key all passed.
+#   GNU grep 3.0 in Git Bash on Windows: `grep -iF` with an ASCII pattern aborts (exit 134), and the pre-commit
+#     scan for private strings read that as "no match".
+#   macOS (BSD grep, bash 3.2): none of it; tr_TR.UTF-8 folds i and I the ASCII way there.
+# The cost: a letter outside ASCII has no other case in the C locale. The two git hooks that scan a user's own
+# words look a second time under the session's locale for a pattern that holds such a letter (_CREW_LOCALE).
+# Byte-identical in every gate; the suite pins it.
+_CREW_LOCALE="${LC_ALL:-${LC_CTYPE:-${LANG:-}}}"
+case "$_CREW_LOCALE" in C|POSIX) _CREW_LOCALE="" ;; esac
+export LC_ALL=C
+# ---- /CREW-LOCALE
+# ---- 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
+_gate_main(){
+local tn st m ti rank=0 floor=0 fname=""
+[ "${CREW_MODEL_ROUTING:-}" = off ] && exit 0
+IFS= read -r -d '' INPUT || true
+# ---- 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 -----------------------------------------------------------------------------------
+_json_slice "$INPUT" tool_name >/dev/null; tn="$_JS"
+case "$tn" in Agent|Task) ;; *) exit 0 ;; esac
+# The call's own fields: everything from "tool_input" on, so a key of the same name in front of it is not read.
+_json_find "$INPUT" '"tool_input"'
+[ "$_JF" -ge 0 ] || exit 0
+ti="${INPUT:_JF}"
+_json_keycount "$ti" subagent_type
+if [ "$_KC" -gt 1 ]; then echo "GUARD (agent model): this call names subagent_type more than once, so which agent it starts cannot be read and the call is refused. Send one." >&2; exit 2; fi
+_json_slice "$ti" subagent_type >/dev/null; _json_unescape "$_JS" >/dev/null; st="$_JU"
+st="${st##*:}"                                  # a plugin names its agents <plugin>:crew-…
+case "$st" in crew-*) ;; *) exit 0 ;; esac
+_json_keycount "$ti" model
+if [ "$_KC" -gt 1 ]; then echo "GUARD (agent model): this call names model more than once, so which model it asks for cannot be read and the call is refused. Send one." >&2; exit 2; fi
+_json_slice "$ti" model >/dev/null; _json_unescape "$_JS" >/dev/null; m="$_JU"
+shopt -s nocasematch
+case "$m" in
+  '')        rank=0 ;;
+  *haiku*)   rank=1; m=haiku ;;
+  *sonnet*)  rank=2; m=sonnet ;;
+  *opus*)    rank=3; m=opus ;;
+  *fable*)   rank=4; m=fable ;;
+  *)         rank=-1 ;;
+esac
+shopt -u nocasematch
+case "$st" in
+  crew-security-expert) floor=3; fname=opus ;;
+  crew-privacy-agent|crew-review-agent|crew-planner|crew-database-expert) floor=2; fname=sonnet ;;
+esac
+if [ "$rank" = 0 ]; then
+  echo "GUARD (agent model): a call to $st has to name its model. Choose haiku, sonnet or opus by the table in CLAUDE.md (risk decides, not size) and repeat the same call with model set.${fname:+ $st runs on $fname or above.}" >&2
+  exit 2
+fi
+if [ "$rank" = -1 ]; then
+  echo "GUARD (agent model): '$m' is not a model this gate knows. Repeat the call to $st with model haiku, sonnet or opus.${fname:+ $st runs on $fname or above.}" >&2
+  exit 2
+fi
+if [ "$rank" = 4 ] && [ "${CREW_ALLOW_FABLE:-}" != 1 ]; then
+  echo "GUARD (agent model): fable is not used for a crew agent unless the user has set CREW_ALLOW_FABLE=1 for the session.${fname:+ $st runs on $fname or above.} Repeat the call to $st with haiku, sonnet or opus, by the table in CLAUDE.md." >&2
+  exit 2
+fi
+if [ "$rank" -lt "$floor" ]; then
+  echo "GUARD (agent model): $st runs on $fname or above, and this call asks for $m. Repeat the same call with model $fname. An audit does not run below the work it clears." >&2
+  exit 2
+fi
+exit 0
+}
+_gate_main "$@"
+_crew_stop "a command of the gate was abandoned"

package/kit/settings.json

@@ -97,6 +97,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-agent-model.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [

package/kit/studio/server/index.js

@@ -205,7 +205,7 @@ async function handle(req, res) {
       const session = await findSession(id);
       if (!session) continue;                 // a session on another machine: not read here, and not guessed
       const u = await cachedUsage(session);
-      usage[id] = { durationMs: u.durationMs, workedMs: u.workedMs, tokens: u.tokens.total, cost: u.cost, unpriced: u.unpriced };
+      usage[id] = { durationMs: u.durationMs, workedMs: u.workedMs, startedAt: u.startedAt, tokens: u.tokens.fresh, cost: u.cost, unpriced: u.unpriced };
     }
     return sendJson(res, 200, { measured: true, usage });
   }

package/kit/studio/server/lib/graph.js

@@ -19,7 +19,7 @@ import path from 'node:path';
 
 import { readAll, contextFill } from './transcript.js';
 import { agentMetaFiles } from './projects.js';
-import { Usage, timesOf } from './usage.js';
+import { Usage, withTimes } from './usage.js';
 import { detailOf } from './permissions.js';
 
 const SESSION_NODE = 'session';
@@ -60,6 +60,74 @@ function harvestCompletions(text, into, at = null) {
   }
 }
 
+// The line the model gate (kit/hooks/guard-agent-model.sh) refuses a call with starts with this, whatever follows.
+const MODEL_GATE = 'GUARD (agent model):';
+
+/**
+ * What the model gate said when it refused a call, or null when the text is not its refusal.
+ * `floor` is the model it says the agent runs on "or above", when it says one; nothing is read into a sentence
+ * that does not say it.
+ */
+export function refusalOf(text) {
+  const at = typeof text === 'string' ? text.indexOf(MODEL_GATE) : -1;
+  if (at === -1) return null;
+  const line = text.slice(at).split('\n')[0].trim();
+  const floor = line.match(/ runs on ([a-z0-9.-]+) or above/);
+  return { text: line.slice(0, 400), floor: floor ? floor[1] : null };
+}
+
+// Which of two models is the larger, for the two questions asked of it: was a call repeated on a higher model,
+// and which is "one model up". A name this does not know has no rank, and nothing is concluded from it.
+const FAMILY = ['haiku', 'sonnet', 'opus', 'fable'];
+export function modelRank(model) {
+  if (typeof model !== 'string') return null;
+  const i = FAMILY.findIndex((f) => model === f || model.includes(`-${f}-`) || model.startsWith(`${f}-`) || model.endsWith(`-${f}`));
+  return i === -1 ? null : i;
+}
+
+/** How a report says it ended: the `confidence: high|low` line a crew agent closes with, or null. */
+export function confidenceOf(text) {
+  const m = typeof text === 'string' ? text.trimEnd().match(/(?:^|\n)\W*confidence:\s*(high|low)\W*$/i) : null;
+  return m ? m[1].toLowerCase() : null;
+}
+
+/**
+ * Tie each agent call to what came before it, where the transcript says so.
+ *
+ * `firstTry` — the gate refused a call and the session made the same call again (same agent, same task): the
+ * call that ran carries what was asked first and why it was refused.
+ * Returns nothing; it writes onto the calls.
+ */
+export function linkRetries(calls) {
+  const list = [...calls.values()].sort((a, b) => a.order - b.order);
+  list.forEach((c, i) => {
+    if (!c.refused) return;
+    const again = list.slice(i + 1).find((n) => n.subagentType === c.subagentType && n.description === c.description);
+    if (!again) return;
+    // A call refused twice keeps the first thing that was asked.
+    again.firstTry = c.firstTry ?? { asked: c.model, floor: c.refused.floor, text: c.refused.text };
+  });
+}
+
+/**
+ * `escalatedFrom` / `escalatedTo` — an agent's report closed with `confidence: low`, and the next call to the same
+ * agent after it reported asked for a higher model: the same work, done again one model up. Read from the order
+ * of the calls, the two reports and the two models; where any of the three is missing nothing is linked.
+ */
+export function linkEscalations(nodes) {
+  const agents = nodes.filter((n) => n.kind === 'agent' && n.order != null).sort((a, b) => a.order - b.order);
+  agents.forEach((low, i) => {
+    if (low.confidence !== 'low' || low.reportedAt == null) return;
+    const from = modelRank(low.model ?? low.modelAsked);
+    if (from === null) return;
+    const again = agents.slice(i + 1).find((n) => n.agentType === low.agentType && n.calledAt != null && n.calledAt >= low.reportedAt);
+    const to = again ? modelRank(again.modelAsked ?? again.model) : null;
+    if (to === null || to <= from || again.escalatedFrom) return;
+    again.escalatedFrom = { id: low.id, from: low.model ?? low.modelAsked, to: again.modelAsked ?? again.model };
+    low.escalatedTo = again.id;
+  });
+}
+
 function scanMain(records) {
   const out = {
     cwd: null, gitBranch: null, version: null, model: null,
@@ -110,6 +178,8 @@ function scanMain(records) {
                 order: out.agentCalls.size + 1,
                 wave: out.waves.get(mid),
                 calledAt: at,
+                // The model the call asked for: its own `model` field. Absent, the agent runs on its default.
+                model: typeof c.input?.model === 'string' ? c.input.model : null,
               });
             }
           }
@@ -119,6 +189,12 @@ function scanMain(records) {
     }
 
     if (r?.type === 'user') {
+      // A call the model gate refused: the answer is an error that carries the gate's own line. No agent started.
+      for (const c of Array.isArray(r.message?.content) ? r.message.content : []) {
+        if (c?.type !== 'tool_result' || c.is_error !== true || !out.agentCalls.has(c.tool_use_id)) continue;
+        const said = refusalOf(textOf(typeof c.content === 'string' ? [{ type: 'text', text: c.content }] : c.content));
+        if (said) out.agentCalls.get(c.tool_use_id).refused = said;
+      }
       out.userTurns += 1;
       harvestCompletions(textOf(r.message?.content), out.completions, at);
     }
@@ -205,11 +281,13 @@ export function openCalls(records) {
 }
 
 /** Roll one agent's own transcript into the numbers its node shows. */
-async function scanAgent(file, usage = null) {
+async function scanAgent(file, usage = null, agentId = null) {
   const { records } = await readAll(file);
-  usage?.add(records);
+  usage?.add(records, agentId ?? 'agents:unnamed');
   const stats = {
     tools: {}, toolCount: 0, lastTool: null, errors: 0,
+    model: null,      // the model its own transcript names: what it actually ran on
+    lastText: null,   // the end of the last thing it said, for the line a report closes with
     tokens: null, startedAt: null, endedAt: null, turns: 0,
     owns: [], // tool_use ids this agent emitted — how nesting is resolved
   };
@@ -224,6 +302,10 @@ async function scanAgent(file, usage = null) {
     }
     if (r?.type === 'assistant') {
       stats.turns += 1;
+      const mdl = r.message?.model;
+      if (typeof mdl === 'string' && mdl && mdl !== '<synthetic>') stats.model = mdl;
+      const said = textOf(r.message?.content);
+      if (said.trim()) stats.lastText = said.slice(-400);
       const u = r.message?.usage;
       if (u && u.cache_read_input_tokens != null) {
         stats.tokens = (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
@@ -274,7 +356,7 @@ async function readAgentDir(subagentsDir, usage = null) {
     // `stats` needs the transcript read; a missing file is a normal state (the
     // agent has not written yet), so absence is a null rather than a throw.
     let stats = null;
-    if (mtime !== null) stats = await scanAgent(jsonl, usage);
+    if (mtime !== null) stats = await scanAgent(jsonl, usage, agentId);
 
     out.push({
       agentId,
@@ -310,6 +392,7 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
   const { records, malformed } = await readAll(session.file);
   const main = scanMain(records);
   // What the session spent, its agents' tokens included and each response counted once.
+  linkRetries(main.agentCalls);
   const usage = new Usage().add(records);
   const agents = await readAgentDir(session.subagentsDir, usage);
   const now = Date.now();
@@ -341,7 +424,7 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
     tokens: contextFill(records),
     startedAt: main.startedAt,
     endedAt: main.updatedAt,
-    usage: { ...usage.result(), ...timesOf(records) },
+    usage: withTimes(usage, records),
     // Commands sent to the background that no notice has ended, oldest first. A session that is over has none
     // running whatever this says: the page shows them only while the session is live.
     backgroundCommands: [...main.background]
@@ -394,7 +477,16 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
       spawnDepth: a.spawnDepth,
       workflow: a.workflow,
       toolUseId: a.toolUseId,
-      model: link?.model ?? null,
+      // The model it ran on: what its own transcript names, and failing that what the launch answer resolved.
+      model: a.stats?.model ?? link?.model ?? null,
+      // The model the call asked for; null when the call named none and the agent ran on its default.
+      modelAsked: call?.model ?? null,
+      // Set when the model gate refused this call the first time it was made: what was asked then, and why not.
+      firstTry: call?.firstTry ?? null,
+      // `confidence: high|low`, the line a crew agent's report closes with; null when it has none.
+      confidence: confidenceOf(a.stats?.lastText ?? null),
+      // Its own share of the session's tokens, and what they cost at list price.
+      usage: usage.of(a.agentId),
       launchStatus: link?.status ?? null,
       // Started in the background, and its transcript stops in the middle of a turn. Such an agent can be quiet
       // for a long time inside one tool call; whether it is still working is the live session's to say, so the
@@ -426,6 +518,8 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
     edges.push({ id: `${parentId}->${a.agentId}`, source: parentId, target: a.agentId, kind: 'spawn' });
   }
 
+  linkEscalations(nodes);
+
   // A workflow run is a real container, not a rendering trick: its agents were
   // spawned by one orchestration script, not by the session directly. Hanging
   // 243 of them straight off the root produced a graph nobody could read, and