crewforth 3.1.0-rc.3 → 3.1.0-rc.4

package/kit/hooks/guard-bash.sh

@@ -1843,6 +1843,62 @@ _appr_named
 [ "$_APN" = 2 ] && block "the approval hook fed by a command (only Claude Code runs it, with the user's message)" "4.4" tamper
 [ "$_APN" = 3 ] && block "a Claude Code session started from a command to continue this one (it could approve for it)" "4.4" tamper
 
+# §4.4: A SESSION STARTED FROM A COMMAND IS NOT HANDED AN APPROVAL. `claude -p "/crew-approve commit"` starts a session
+# whose only message is the approval; that session would record it and commit, and this one would have approved for
+# the user. hooks/prompt-approval.sh refuses to record in a headless session and at a session's first message, which
+# is the protection; this is the second line, for the forms a command spells out. A command that names claude (so
+# also `npx @anthropic-ai/claude-code`, `bunx`, `node …/claude-code/cli.js`) is read word by word, the way the shell
+# splits it, and refused when one WORD is an approval: a quoted argument, an escaped one, the value of an option
+# (`--prompt=…`) or of a variable (`p='…'`), a text echoed into it. Which text is an approval is asked of the one
+# function that reads the user's prompt, _crew_appr_op, sourced from prompt-approval.sh. The prompt of an ordinary
+# `claude -p "…"` is not an approval and nothing here touches it.
+# HONEST SCOPE: a prompt read from a file, built by printf, or written with an escape the shell decodes (`$'\x2f…'`)
+# is not spelled in the command, and is past this rule.
+_appr_word(){  # $1 = a word of the command -> 0 when it, or what follows its first `=`, is an approval
+  local w="$1"
+  [ "${#w}" -le 160 ] || return 1
+  _crew_appr_op "$w"; [ -n "$OP" ] && return 0
+  case "$w" in *=*) _crew_appr_op "${w#*=}"; [ -n "$OP" ] && return 0 ;; esac
+  return 1
+}
+_appr_in_claude_call(){  # 0 = a word of this command is an approval (OP names it)
+  # The command AS IT WAS SENT: the prompt of a plain `claude -p "…"` has been taken out of CMD by now (it is text for
+  # another session, not a command of this one), and it is exactly the word this rule has to read.
+  local s="${CMD_REAL:-$CMD}" w="" pre c body inw=0 nc=0 here="${BASH_SOURCE%/*}"
+  [ "$here" = "${BASH_SOURCE}" ] && here=.
+  shopt -q nocasematch && nc=1; shopt -s nocasematch
+  case "$s" in *claude*) [ "$nc" = 0 ] && shopt -u nocasematch ;; *) [ "$nc" = 0 ] && shopt -u nocasematch; return 1 ;; esac
+  [ -f "$here/prompt-approval.sh" ] || return 1          # no recording hook: no approval can be recorded at all
+  declare -F _crew_appr_op >/dev/null 2>&1 || . "$here/prompt-approval.sh"
+  declare -F _crew_appr_op >/dev/null 2>&1 || return 1
+  OP=""
+  while :; do
+    pre="${s%%[\"\'\\$' \t\n;|&()<>']*}"
+    [ -n "$pre" ] && { w="$w$pre"; inw=1; }
+    [ "$pre" = "$s" ] && break
+    c="${s:${#pre}:1}"; s="${s:${#pre}+1}"
+    case "$c" in
+      \\) case "$s" in $'\n'*) s="${s:1}" ;; *) w="$w${s:0:1}"; s="${s:1}"; inw=1 ;; esac ;;
+      \') [ "${w%\$}" != "$w" ] && w="${w%\$}"                # $'…': the text is kept as written
+          body="${s%%\'*}"; if [ "$body" = "$s" ]; then s=""; else s="${s:${#body}+1}"; fi
+          w="$w$body"; inw=1 ;;
+      \") inw=1
+          while :; do
+            body="${s%%[\"\\]*}"; w="$w$body"
+            [ "$body" = "$s" ] && { s=""; break; }
+            c="${s:${#body}:1}"; s="${s:${#body}+1}"
+            [ "$c" = '"' ] && break
+            w="$w${s:0:1}"; s="${s:1}"
+          done ;;
+      *)  if [ "$inw" = 1 ]; then _appr_word "$w" && return 0; fi
+          w=""; inw=0 ;;
+    esac
+  done
+  [ "$inw" = 1 ] && _appr_word "$w" && return 0
+  return 1
+}
+_appr_in_claude_call && block "a command that hands a Claude Code session an approval as its prompt (only the user's own message approves)" "4.4" tamper
+
 # §4.5-adjacent: a .env file holds secrets. The settings.json Read-tool deny does NOT cover the Bash tool, so a
 # `cat .env` would surface them. Block the direct-file readers/copiers and a `< .env` input redirect on a
 # .env / .env.<env> file; the templates (.env.example/.sample/.template/.dist) stay readable. Arg-taking readers
@@ -2155,7 +2211,7 @@ _crew_appr_path(){  # $1 = a directory -> _AP: the record's path in that worktre
 }
 # ---- /CREW-APPROVAL-PATH ---------------------------------------------------------------------------------
 # §4.4 IN `auto` AND `dontAsk`: THE USER'S OWN MESSAGE IS THE APPROVAL. hooks/prompt-approval.sh records it when the
-# whole message is `approve: commit` / `push` / `commit+push` (or `onay: …`), with what git reported at that moment.
+# whole message is `/crew-approve commit` / `push` / `commit+push` (or the older `approve: …`), with what git reported at that moment.
 # This reads the record back and answers one question: does it cover THIS call, and nothing else?
 #   commit       the index writes the recorded tree and HEAD is the recorded one. A commit moves HEAD, so the same
 #                record cannot allow a second one; a commit that FAILED (a hook refused it) moved nothing and may be retried.
@@ -3167,7 +3223,7 @@ ${BRANCH_WARN}Approve only if the commit message above was shown to you and you
       if ! _appr_wired; then
         # The record is written by one hook. Where it is not wired, a message from the user records nothing, and
         # telling them to type one sends them into a wall (measured in the field: a worktree on an older Crewforth).
-        echo "THE APPROVAL PATH IS CLOSED IN THIS SESSION: the hook that records the user's approval (prompt-approval.sh) is not wired on UserPromptSubmit in the settings in effect ($_APRW). A message 'approve: …' records nothing here." >&2
+        echo "THE APPROVAL PATH IS CLOSED IN THIS SESSION: the hook that records the user's approval (prompt-approval.sh) is not wired on UserPromptSubmit in the settings in effect ($_APRW). A '/crew-approve' message records nothing here." >&2
         echo "Tell the user exactly that, in their language, and give them the two ways that work: Shift+Tab to default/acceptEdits (this gate then asks them directly), or the command in their own terminal." >&2
         echo "Do not create an approval any other way." >&2
         exit 2
@@ -3175,9 +3231,9 @@ ${BRANCH_WARN}Approve only if the commit message above was shown to you and you
       _aps=push; git_has "$CMD_SEEN" 'commit' && _aps=commit
       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
-      echo "  2. under it ONE line:  If you approve, write only this: approve: $_aps" >&2
-      echo "     (in Turkish:  Onaylıyorsan yalnız şunu yaz: onay: $_aps). Name the one that fits: commit, push, or commit+push when a push follows the commit." >&2
-      echo "Their reply has to be that text alone: a sentence such as 'go ahead and commit' is not an approval. It is tied to the staged tree and HEAD, lasts 30 minutes and ends at their next message." >&2
+      echo "  2. under it ONE line, the sentence in their language and the command as it is (only the user can type it):  If you approve, send only this: /crew-approve $_aps" >&2
+      echo "     Name the one the user can type for this call: /crew-approve commit, /crew-approve push, or /crew-approve commit+push when a push follows the commit." >&2
+      echo "Their message has to be that command alone, typed by them: a sentence such as 'go ahead and commit' is not an approval, and you cannot run the command for them. It is tied to the staged tree and HEAD, lasts 30 minutes and ends at their next message." >&2
       echo "Then run the command ALONE in its call (no cd, no pipe, nothing chained): git commit -m '…', or git push <remote> <branch>." >&2
       echo "The other ways: Shift+Tab to default/acceptEdits (this gate then asks them directly), or the command in their own terminal." >&2
       echo "Only the user can write that message. Do not write it for them, and do not create an approval any other way." >&2

package/kit/hooks/guard-schedule.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# guard-schedule.sh - a prompt a tool schedules is not the user's (§4.4).
+#
+# WHY. In `auto` and `dontAsk` the approval for a commit or a push is what the user types: `/crew-approve commit`,
+# recorded by hooks/prompt-approval.sh from UserPromptSubmit. A prompt that a tool SCHEDULES raises the same event
+# when it fires. So a session that scheduled `/crew-approve commit` would be approving its own commit.
+#
+# WHAT. Wired on PreToolUse for the tools that schedule a prompt (CronCreate, ScheduleWakeup, RemoteTrigger, and an
+# MCP tool whose name holds trigger, schedule, cron or later). The call is refused when ANY string in its input is
+# an approval, by the function that reads the user's own prompt: prompt-approval.sh is sourced for it, so there is
+# one definition of what an approval is. An ordinary scheduled prompt holds no such string and passes untouched.
+#
+# COST. One awk on these few tools, to take the strings out of the payload; nothing on any other tool call.
+# HONEST SCOPE. A tool this hook is not wired on, or a prompt put together only when it fires, is past it.
+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 here="${BASH_SOURCE%/*}" strs sv tn sch=0
+[ "$here" = "${BASH_SOURCE}" ] && here=.
+IFS= read -r -d '' INPUT || true
+if [ ! -f "$here/prompt-approval.sh" ]; then
+  echo "GUARD (§4.4): prompt-approval.sh is not beside this gate, so a scheduled prompt cannot be checked for an approval and the call is refused. Update Crewforth." >&2
+  exit 2
+fi
+. "$here/prompt-approval.sh"
+declare -F _crew_appr_op >/dev/null 2>&1 || { echo "GUARD (§4.4): prompt-approval.sh did not give the approval check, so the call is refused. Update Crewforth." >&2; exit 2; }
+_json_slice "$INPUT" tool_name >/dev/null; tn="$_JS"
+shopt -s nocasematch
+case "$tn" in *cron*|*schedul*|*trigger*|*later*|*wakeup*) sch=1 ;; esac
+shopt -u nocasematch
+[ "$sch" = 1 ] || exit 0
+# Every JSON string of at most 120 bytes, still escaped, one per line (a JSON string holds no raw newline). An
+# approval is a few words: a longer string is never one, and is not kept.
+strs="$(printf '%s' "$INPUT" | LC_ALL=C awk '{ buf = buf $0 " " } END { n = length(buf); ins = 0; esc = 0; s = ""; big = 0
+    for (i = 1; i <= n; i++) { c = substr(buf, i, 1)
+      if (!ins) { if (c == "\"") { ins = 1; s = ""; big = 0 }; continue }
+      if (esc) { esc = 0; if (!big) s = s c; continue }
+      if (c == "\\") { esc = 1; if (!big) s = s c; continue }
+      if (c == "\"") { ins = 0; if (!big) print s; continue }
+      if (!big) { s = s c; if (length(s) > 120) big = 1 } } }')" || {
+  echo "GUARD (§4.4): the prompt this call schedules could not be read (awk did not run), so the call is refused." >&2; exit 2; }
+while IFS= read -r sv; do
+  [ -n "$sv" ] || continue
+  _json_unescape "$sv" >/dev/null; _crew_appr_op "$_JU"
+  if [ -n "$OP" ]; then
+    echo "GUARD (§4.4): this call schedules a prompt that is an approval for a commit or a push ($OP). An approval is what the user types; a prompt a tool schedules would approve in their place, so the call is refused." >&2
+    echo "Schedule the work without it. For the approval itself, show the commit message and ask: the user can type /crew-approve $OP when they agree." >&2
+    exit 2
+  fi
+done <<< "$strs"
+exit 0
+}
+_gate_main "$@"
+_crew_stop "a command of the gate was abandoned"

package/kit/hooks/prompt-approval.sh

@@ -8,8 +8,8 @@
 # yes, and this hook is the only thing that turns it into a record.
 #
 # WHAT COUNTS. The WHOLE message, trimmed, is one of (letter case does not matter):
-#     approve: commit      approve: push      approve: commit+push
-#     onay: commit         onay: push         onay: commit+push
+#     /crew-approve commit      /crew-approve push      /crew-approve commit+push
+# and, as the release candidates of 3.1.0 had it, `approve: <what>` or `onay: <what>`.
 # A sentence that contains those words is not an approval, and neither is a message with a second line: text
 # that was pasted, quoted or relayed from somewhere else never has that shape by accident.
 #
@@ -51,8 +51,13 @@ _CREW_LOCALE="${LC_ALL:-${LC_CTYPE:-${LANG:-}}}"
 case "$_CREW_LOCALE" in C|POSIX) _CREW_LOCALE="" ;; esac
 export LC_ALL=C
 # ---- /CREW-LOCALE
-IFS= read -r -d '' INPUT || true
-case "$INPUT" in *'"hook_event_name"'*UserPromptSubmit*) ;; *) exit 0 ;; esac
+# guard-schedule.sh SOURCES this file for one thing, _crew_appr_op: which text is an approval is decided here and
+# nowhere else. Sourced, the file defines its functions and returns before anything is read or written.
+_PA_LIB=0; [ "${BASH_SOURCE[0]}" != "$0" ] && _PA_LIB=1
+if [ "$_PA_LIB" = 0 ]; then
+  IFS= read -r -d '' INPUT || true
+  case "$INPUT" in *'"hook_event_name"'*UserPromptSubmit*) ;; *) exit 0 ;; esac
+fi
 # ---- 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
@@ -351,6 +356,38 @@ _crew_appr_path(){  # $1 = a directory -> _AP: the record's path in that worktre
 }
 # ---- /CREW-APPROVAL-PATH ---------------------------------------------------------------------------------
 
+# ---- WHICH TEXT IS AN APPROVAL: one function, asked here of the user's prompt and by guard-schedule.sh of a
+# prompt a tool is about to schedule ---------------------------------------------------------------------------
+_crew_appr_op(){  # $1 = a text, decoded -> OP: commit | push | commit+push, or "" when the text is not an approval
+  local P="$1" _k _v LC_ALL=C
+  OP=""
+  P="${P//$'\r'/}"
+  while :; do case "$P" in [$' \t\n']*) P="${P:1}" ;; *) break ;; esac; done
+  while :; do case "$P" in *[$' \t\n']) P="${P%?}" ;; *) break ;; esac; done
+  [ "${#P}" -le 40 ] || return 0
+  case "$P" in
+    *$'\n'*) return 0 ;;
+    # THE COMMAND: `/crew-approve <what>`, or `/<plugin>:crew-approve <what>` as a plugin names its commands. Measured
+    # on Claude Code 2.1.284: a command the user types reaches UserPromptSubmit with `prompt` as typed, and a skill
+    # the model starts with the Skill tool raises PreToolUse and PostToolUse only, never that event.
+    /*) _k="${P%%[$' \t']*}"; [ "$_k" != "$P" ] || return 0
+        _v="${P:${#_k}}"; _k="${_k#/}"; _k="@${_k##*:}" ;;      # `@`: a command, so `crew-approve: commit` as text is not one
+    # The text form of 3.1.0's release candidates, kept: `approve: <what>` and `onay: <what>`.
+    *:*) _k="${P%%:*}"; _v="${P#*:}" ;;
+    *) return 0 ;;
+  esac
+  _k="${_k//[$' \t']/}"; _v="${_v//[$' \t']/}"
+  # In the C locale: under tr_TR an upper-case I does not fold to i, and `ONAY: COMMIT` was not an approval (review).
+  shopt -s nocasematch
+  case "$_k" in
+    @crew-approve|approve|onay)
+      case "$_v" in commit) OP=commit ;; push) OP=push ;; commit+push) OP=commit+push ;; esac ;;
+  esac
+  shopt -u nocasematch
+}
+
+[ "$_PA_LIB" = 1 ] && return 0
+
 # A second "prompt" key cannot come from the text of a prompt (inside a JSON string every quote is escaped), so
 # more than one means the payload is not the shape this hook knows, and nothing is read from it.
 _json_keycount "$INPUT" prompt; _n_prompt=$_KC
@@ -384,23 +421,8 @@ if [ -n "$REC" ] && [ -s "$REC" ]; then : > "$REC" 2>/dev/null || true; fi
 # ---- is this message an approval? ------------------------------------------------------------------------
 [ "$_n_prompt" = 1 ] || exit 0
 [ "${#RAW}" -le 120 ] || exit 0        # an approval is a few words; a pasted page is not decoded to find that out
-_json_unescape "$RAW" >/dev/null; P="$_JU"
-P="${P//$'\r'/}"
-while :; do case "$P" in [$' \t\n']*) P="${P:1}" ;; *) break ;; esac; done
-while :; do case "$P" in *[$' \t\n']) P="${P%?}" ;; *) break ;; esac; done
-[ "${#P}" -le 40 ] || exit 0
-case "$P" in *$'\n'*) exit 0 ;; *:*) ;; *) exit 0 ;; esac
-_k="${P%%:*}"; _v="${P#*:}"
-_k="${_k//[$' \t']/}"; _v="${_v//[$' \t']/}"
-OP=""
-# In the C locale: under tr_TR an upper-case I does not fold to i, and `ONAY: COMMIT` was not an approval (review).
-_pa_match(){ local LC_ALL=C; shopt -s nocasematch
-  case "$_k" in
-    approve|onay)
-      case "$_v" in commit) OP=commit ;; push) OP=push ;; commit+push) OP=commit+push ;; esac ;;
-  esac
-  shopt -u nocasematch; }
-_pa_match
+_json_unescape "$RAW" >/dev/null
+_crew_appr_op "$_JU"
 [ -n "$OP" ] || exit 0
 
 # From here on the message IS an approval, so every way of not recording it says why - to the user and to the
@@ -420,6 +442,31 @@ case "$PM" in
 esac
 [ -n "$REC" ] || no "this directory is not inside a git repository."
 
+# A PERSON, IN A SESSION THAT HAS SHOWN THEM SOMETHING. A session can start another one and hand it the approval as
+# its prompt: `claude -p "/crew-approve commit"`, or an interactive one driven through a pseudo-terminal. That
+# session's only message is the approval, this hook would record it, and the session would then commit: the first
+# session has approved for the user. Measured on Claude Code 2.1.294 (macOS), from a hook that printed what it saw:
+#   started how                                CLAUDE_CODE_SESSION_ATTENDED   the transcript file when this hook runs
+#   claude -p, from a session's Bash           0 (set to 1 by the caller: still 0)   not there (first message)
+#   claude -p, from an emptied environment     0                               not there (first message)
+#   interactive, in a pty, from a session      1                               not there, and never written: a
+#                                                                              session started inside another keeps none
+#   interactive, in a pty, emptied environment 1                               not there at the first message; there after
+#   the desktop app, a conversation under way  1                               there
+# Nothing else told them apart: the payload has the same fields, CLAUDECODE and CLAUDE_CODE_CHILD_SESSION are 1 in
+# all of them, CLAUDE_CODE_ENTRYPOINT is inherited from the outer session, and no hook has a terminal on stdin.
+# So two things are asked. Neither is a documented contract, and both fail towards NOT recording:
+#   1. the session is not a headless one;
+#   2. the session's transcript is already on disk when the approval arrives, so the approval is not the session's
+#      first message and the session is not one that keeps no transcript.
+# HONEST SCOPE: a session started with an emptied environment and driven through a pseudo-terminal for a second
+# message passes both. guard-bash.sh refuses the forms of that it can read; a program that types is past it.
+case "${CLAUDE_CODE_SESSION_ATTENDED-}" in
+  0) no "this session has nobody in front of it (it was started with -p, or by a program), and an approval is what a person types into their own session." ;;
+esac
+_json_slice "$INPUT" transcript_path >/dev/null; _json_unescape "$_JS" >/dev/null; TP="${_JU//\\//}"
+{ [ -n "$TP" ] && [ -s "$TP" ]; } || no "this is the first message of this session, or the session keeps no transcript (one started from inside another session keeps none). An approval answers a commit message the session has shown: have it shown, then approve."
+
 # The session the user is writing in. guard-bash.sh accepts the record only from that one: a session started by a
 # command can be handed any prompt.
 _json_slice "$INPUT" session_id >/dev/null; SID="$_JS"

package/kit/settings.json

@@ -86,6 +86,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "CronCreate|ScheduleWakeup|RemoteTrigger|mcp__.*([Tt]rigger|[Ss]chedul|[Cc]ron|[Ll]ater).*",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/guard-schedule.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [

package/kit/skills/crew-approve/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: crew-approve
+description: Approve the commit or push Claude just showed you (auto and dontAsk modes).
+argument-hint: "[commit | push | commit+push]"
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-approve
+Argument: $ARGUMENTS
+
+The user typed this command. Typing it is the approval: `hooks/prompt-approval.sh` read the message itself and
+recorded it, tied to what is staged, to `HEAD` and to this session, for 30 minutes or until the user's next
+message. Nothing in this text records anything, and you cannot give this approval for the user.
+
+Read the line Crewforth added to this turn and do what it says:
+
+- **"approval recorded"**: run exactly what it names, each command alone in its call. A commit is
+  `git commit -m '…'` with the message you showed (single-quoted, or from a here-document with a quoted delimiter);
+  a push is `git push <remote> <branch>`. The review record of §4.6 is still required.
+- **"approval NOT recorded"**: tell the user the reason it gives, and run nothing.
+- **No such line**: the session is in a mode where the gate asks the user itself (`default`, `acceptEdits`), or
+  the argument was not `commit`, `push` or `commit+push`. Say which, and in the first case run the command and let
+  the gate's own prompt ask.
+
+Force-push and the rest of §4.5 are not opened by this.

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

@@ -67,6 +67,7 @@ function scanMain(records) {
     agentCalls: new Map(),   // toolUseId -> { subagentType, description }
     links: new Map(),        // toolUseId -> { agentId, status, model }
     completions: new Map(),  // task id (an agent's, or a background command's) -> { status, at }
+    waves: new Map(),        // assistant message id -> wave number, in the order the messages were written
     commands: new Map(),     // toolUseId -> the command a Bash call ran
     background: new Map(),   // background task id -> { toolUseId, startedAt }
     owners: new Map(),       // toolUseId -> owner node id
@@ -97,10 +98,18 @@ function scanMain(records) {
           if (c?.type === 'tool_use' && c.id) {
             out.owners.set(c.id, SESSION_NODE);
             if (typeof c.input?.command === 'string') out.commands.set(c.id, c.input.command);
-            if (c.name === 'Agent') {
+            if (c.name === 'Agent' || c.name === 'Task') {
+              // The order the session called its agents in, and which calls were made together: the calls of one
+              // assistant message are one wave. A message is written as several records, one per block, and they
+              // share its id — so the wave is the message id, not the record.
+              const mid = r.message?.id ?? `record:${out.agentCalls.size}`;
+              if (!out.waves.has(mid)) out.waves.set(mid, out.waves.size + 1);
               out.agentCalls.set(c.id, {
                 subagentType: c.input?.subagent_type ?? null,
                 description: c.input?.description ?? null,
+                order: out.agentCalls.size + 1,
+                wave: out.waves.get(mid),
+                calledAt: at,
               });
             }
           }
@@ -119,7 +128,8 @@ function scanMain(records) {
     if (tur && typeof tur === 'object' && tur.agentId) {
       const id = r.message?.content?.find?.((c) => c?.type === 'tool_result')?.tool_use_id
         ?? r.toolUseID ?? null;
-      const entry = { agentId: tur.agentId, status: tur.status ?? null, model: tur.resolvedModel ?? null };
+      // `at` is when the answer was written: for a call the session waited on, that is when the agent reported.
+      const entry = { agentId: tur.agentId, status: tur.status ?? null, model: tur.resolvedModel ?? null, at };
       if (id) out.links.set(id, entry);
       else out.links.set(`agent:${tur.agentId}`, entry);
     }
@@ -314,6 +324,8 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
   // toolUseId -> agentId, from the returning result record.
   const byToolUse = new Map();
   for (const [k, v] of main.links) if (!k.startsWith('agent:')) byToolUse.set(k, v);
+  const callOf = new Map();
+  for (const [k, v] of byToolUse) callOf.set(v.agentId, k);
 
   const nodes = [{
     id: SESSION_NODE,
@@ -345,8 +357,10 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
   const edges = [];
 
   for (const a of agents) {
-    const call = a.toolUseId ? main.agentCalls.get(a.toolUseId) : null;
-    const link = a.toolUseId ? byToolUse.get(a.toolUseId) : null;
+    // The call that started it: named by its own meta file, or found from the answer that named the agent.
+    const callId = a.toolUseId ?? callOf.get(a.agentId) ?? null;
+    const call = callId ? main.agentCalls.get(callId) : null;
+    const link = callId ? byToolUse.get(callId) : null;
     const notice = main.completions.get(a.agentId) ?? null;
     const completion = noticeStands(notice, a.stats?.endedAt ?? null) ? notice.status : null;
 
@@ -398,6 +412,15 @@ export async function buildGraph(session, { staleMs = STALE_MS } = {}) {
       endedAt: a.stats?.endedAt ?? null,
       durationMs: a.stats?.durationMs ?? null,
       updatedAt: a.mtime,
+      // Where it stands among the agents the session called: its place in the order of the calls, the wave it
+      // was called in, and when. Null for an agent the session's own transcript did not call (one a workflow
+      // started): nothing is known about its place from here.
+      order: call?.order ?? null,
+      wave: call?.wave ?? null,
+      calledAt: call?.calledAt ?? null,
+      // When it handed its result back: the answer to a call the session waited on, or the notice that ended a
+      // background agent. Null while it has not, and when no time was recorded.
+      reportedAt: link?.status === 'completed' ? (link.at ?? null) : (completion ? (notice.at ?? null) : null),
     });
 
     edges.push({ id: `${parentId}->${a.agentId}`, source: parentId, target: a.agentId, kind: 'spawn' });

package/kit/studio/web/app.js

@@ -419,7 +419,7 @@ el.newSession.addEventListener('click', () => {
 
 /* The toolbar says what the canvas is doing. It is painted from the canvas's own
    state, so a choice restored from storage shows without being re-made. */
-const GROUP_WORD = { run: 'Workflow run', type: 'Agent type', parent: 'Parent', none: 'None' };
+const GROUP_WORD = { run: 'Workflow run', type: 'Agent type', parent: 'Parent', order: 'Order', none: 'None' };
 const DENSITY_WORD = { auto: 'Auto', comfortable: 'Comfortable', compact: 'Compact' };
 const SHOW = {
   all: { word: 'All', statuses: null },

package/kit/studio/web/canvas.js

@@ -11,10 +11,11 @@
 //   A status is never colour alone: every dot has its word beside it.
 //   A poll that changed nothing writes nothing. Each element remembers what it last drew.
 import {
-  plan, sequence, crowdFolds, fitZoom, stateOf, ZOOM, GROUPINGS, DENSITIES,
+  plan, sequence, crowdFolds, fitZoom, stateOf, ZOOM, GROUPINGS, DENSITIES, INFERRED_NOTE,
 } from './graph-plan.js';
+import { clock } from './timeline-plan.js';
 import { agentStatus } from './nav.js';
-import { roleName, shownType, hoverOf } from './names.js';
+import { roleName, shownType, hoverOf, orderTag } from './names.js';
 
 // How long an arriving wire takes to draw itself toward its new card. Short on purpose: this is a status panel,
 // and anything a viewer has to wait through is a cost they pay on every spawn.
@@ -213,6 +214,10 @@ export class Canvas {
     const rows = mk('div', 'cv-legend-grid');
     rows.append(line('live', 'working now'), line('waiting', 'needs you'), line('done', 'finished'), line('failed', 'failed'));
     box.append(rows);
+    // The one wire that is not a call: in the Order view, from an agent to the wave called after it reported.
+    const inferred = line('inferred', 'after it reported (inferred, not a call)');
+    inferred.title = INFERRED_NOTE;
+    box.append(inferred);
     const marks = mk('div', 'cv-legend-grid');
     this.legendBuiltin = mk('span', 'cv-tile cv-tile-sm');
     const crew = mk('span', 'cv-tile cv-tile-sm');
@@ -647,7 +652,7 @@ export class Canvas {
     el.classList.toggle('cv-pinned', Boolean(it.pinned));
     if (it.kind === 'session') this.#fillSession(el, it);
     else if (it.kind === 'group') this.#fillGroup(el, it, liveCells);
-    else this.#fillAgent(el, it.node, it.compact);
+    else this.#fillAgent(el, it.node, it.compact, it.after ?? null);
   }
 
   /** The skeleton of a card: the parts it will fill. */
@@ -686,18 +691,24 @@ export class Canvas {
     } else if (it.compact) {
       el.classList.add('cv-chip');
       p.dot = mk('span', 'dot');
+      p.order = mk('span', 'cv-order');
       p.name = mk('span', 'cv-name');
       p.task = mk('span', 'cv-task');
       p.word = mk('span', 'cv-word');
-      el.append(p.dot, p.name, p.task, p.word);
+      el.append(p.dot, p.order, p.name, p.task, p.word);
     } else {
       p.tile = mk('span', 'cv-tile');
       p.name = mk('span', 'cv-name');
+      p.order = mk('span', 'cv-order');
       p.pill = this.#pill();
       const row = mk('div', 'cv-row');
       row.append(p.tile, p.name, mk('span', 'cv-fill'), p.pill.el);
-      p.task = mk('div', 'cv-task cv-indent');
-      el.append(row, p.task);
+      // The second line: the task, and at its end where the card stands in the order of the calls. The name
+      // keeps the first line to itself.
+      p.task = mk('span', 'cv-task');
+      const under = mk('div', 'cv-under cv-indent');
+      under.append(p.task, p.order);
+      el.append(row, under);
     }
     el.parts = p;
   }
@@ -768,13 +779,15 @@ export class Canvas {
     el.setAttribute('aria-label', `Session, ${st?.word ?? 'state not measured'}, ${p.name.textContent}, ${p.sub.textContent}`);
   }
 
-  #fillAgent(el, n, compact) {
+  #fillAgent(el, n, compact, after = null) {
     const st = this.#statusOf(n);
     const who = compact ? this.#identity(n) : this.#fillTile(el.parts.tile, n);
     const type = n.kind === 'workflow' ? (n.workflowId ?? 'workflow run') : shownType(n);
     const task = n.kind === 'workflow' ? `${n.members ?? 0} agents` : (n.description ?? '');
     const dim = this.dimmed(n);
-    const sig = JSON.stringify([type, task, st.word, st.tone, st.state, who.source, dim, n.status]);
+    // Its place in the order the session called its agents, and when: "#3 · 09:14". A chip has room for the number.
+    const tag = orderTag(n, compact ? null : clock);
+    const sig = JSON.stringify([type, task, st.word, st.tone, st.state, who.source, dim, n.status, tag, after]);
     if (el.sig === sig) return;
     el.sig = sig;
     const p = el.parts;
@@ -789,6 +802,11 @@ export class Canvas {
     // Both are cut to the card's width; hovering says them whole, and the type as it is declared.
     p.name.title = n.kind === 'workflow' ? '' : (n.agentType ?? '');
     p.task.title = task;
+    p.order.textContent = tag;
+    p.order.hidden = !tag;
+    p.order.title = tag ? `Called ${orderTag(n, clock)} by the session` : '';
+    // In the Order view: what had reported before this wave was called. A reading of the order of events.
+    el.title = after?.length ? `Called after ${after.join(', ')} reported.\n${INFERRED_NOTE}` : '';
     if (compact) {
       p.dot.dataset.tone = st.tone ?? 'none';
       p.word.textContent = st.word;
@@ -806,7 +824,7 @@ export class Canvas {
     const p = el.parts;
     const counts = it.counts;
     const says = Object.entries(counts).map(([s, c]) => `${c} ${agentStatus(s).word}`).join(' · ');
-    const sig = JSON.stringify([it.label, says, it.open, it.boxed, it.type, it.status]);
+    const sig = JSON.stringify([it.label, says, it.open, it.boxed, it.type, it.status, it.first?.order ?? null]);
     if (el.sig !== sig) {
       el.sig = sig;
       el.dataset.state = stateOf(it.status);
@@ -820,7 +838,9 @@ export class Canvas {
       if (it.type === 'run') { p.tile.innerHTML = MARK.run; p.tile.title = 'Workflow run'; }
       else this.#fillTile(p.tile, it.type === 'type' ? { agentType: it.agentType } : (it.of ?? {}));
       // Several agents of one type: the number is a badge beside the role. Any other group says how many it holds.
-      p.sub.textContent = it.type === 'type' ? `× ${it.count}` : `${it.members.length} ${it.members.length === 1 ? 'agent' : 'agents'}`;
+      const size = it.type === 'type' ? `× ${it.count}` : `${it.members.length} ${it.members.length === 1 ? 'agent' : 'agents'}`;
+      // The group stands where its first member does in the order of the calls.
+      p.sub.textContent = [orderTag(it.first), size].filter(Boolean).join(' · ');
       p.sub.classList.toggle('cv-times', it.type === 'type');
       p.fold.innerHTML = it.boxed ? MARK.down : MARK.chevron;
       // Read aloud, the badge is part of the name.
@@ -856,8 +876,9 @@ export class Canvas {
         c.tabIndex = 0;
         const q = {};
         if (!it.grid) { q.tile = mk('span', 'cv-tile'); c.append(q.tile); } else { q.dot = mk('span', 'dot'); c.append(q.dot); }
+        q.order = mk('span', 'cv-order');
         q.name = mk('span', 'cv-name');
-        c.append(q.name);
+        c.append(q.order, q.name);
         if (!it.grid) { c.append(mk('span', 'cv-fill')); q.dot = mk('span', 'dot'); c.append(q.dot); }
         q.word = mk('span', 'cv-word');
         c.append(q.word);
@@ -879,7 +900,8 @@ export class Canvas {
       // Inside a group of one type the type is the group's name, so a member is told apart by its task.
       const text = it.type === 'type' ? (n.description || shownType(n) || n.id) : shownType(n);
       const dim = this.dimmed(n);
-      const csig = JSON.stringify([text, st.word, st.tone, st.state, dim, this.selected === n.id]);
+      const ctag = orderTag(n, it.grid ? null : clock);
+      const csig = JSON.stringify([text, st.word, st.tone, st.state, dim, this.selected === n.id, ctag]);
       if (c.sig === csig) continue;
       c.sig = csig;
       c.dataset.state = st.state;
@@ -887,6 +909,8 @@ export class Canvas {
       c.classList.toggle('cv-dim', dim);
       c.classList.toggle('cv-selected', this.selected === n.id);
       c.parts.name.textContent = text;
+      c.parts.order.textContent = ctag;
+      c.parts.order.hidden = !ctag;
       c.title = hoverOf(n);
       c.parts.dot.dataset.tone = st.tone ?? 'none';
       c.parts.word.textContent = st.word;
@@ -894,6 +918,30 @@ export class Canvas {
     }
   }
 
+  /** What an inferred wire says: on hover that it is an inference, and once per reporter, in words beside it. */
+  #edgeWords(path, e, c) {
+    const title = e.title ?? '';
+    if (path.said !== title) {
+      path.said = title;
+      path.querySelector?.('title')?.remove();
+      if (title) {
+        const t = document.createElementNS(SVG, 'title');
+        t.textContent = title;
+        path.append(t);
+      }
+    }
+    if (!e.label) { path.label?.remove(); path.label = null; return; }
+    if (!path.label) {
+      path.label = document.createElementNS(SVG, 'text');
+      path.label.setAttribute('class', 'cv-edge-label');
+      this.edgeG.append(path.label);
+    }
+    path.label.textContent = e.label;
+    // Just off the reporter's edge, above the wire, where it does not sit on a card.
+    path.label.setAttribute('x', String(e.from.x + 8));
+    path.label.setAttribute('y', String(e.from.y - 6));
+  }
+
   // Wires are kept and updated, never rebuilt.
   //
   // Replacing the whole layer each pass was the reason motion could not live here: a CSS animation restarts when
@@ -932,9 +980,13 @@ export class Canvas {
 
       const target = this.nodes.get(e.target);
       const waiting = target && this.waiting.has(target.id);
-      const state = waiting ? 'waiting' : e.state;
+      // A wire that is a reading of the order of events says nothing about what its target is doing now.
+      const inferred = e.kind === 'inferred';
+      const state = inferred ? 'inferred' : (waiting ? 'waiting' : e.state);
       path.dataset.status = e.status;
       path.dataset.state = state;
+      path.dataset.kind = inferred ? 'inferred' : 'call';
+      this.#edgeWords(path, e, c);
       path.classList.toggle('cv-dim', Boolean(target) && this.dimmed(target));
       path.classList.toggle('cv-path', onPath.has(e.target));
 
@@ -950,6 +1002,7 @@ export class Canvas {
 
     for (const [key, path] of this.edgeEls) {
       if (alive.has(key)) continue;
+      path.label?.remove();
       path.remove();
       this.edgeEls.delete(key);
     }