cleargate 0.8.2 → 0.10.0

package/templates/cleargate-planning/.claude/hooks/token-ledger.sh

@@ -5,31 +5,46 @@
 # Output: appends to .cleargate/sprint-runs/<sprint-id>/token-ledger.jsonl
 # Cost computation is deferred to the Reporter agent (prices change; keep raw).
 #
-# Active sprint detection (FIXED 2026-04-19):
+# ── Per-task sentinel contract (ADDED 2026-04-20) ─────────────────────────────
+#
+#   Before each Task (Agent) dispatch the orchestrator writes:
+#     .cleargate/sprint-runs/<sprint>/.pending-task-<N>.json
+#   with shape:
+#     { "agent_type": "developer"|"architect"|"qa"|"reporter",
+#       "work_item_id": "STORY-006-01",
+#       "turn_index": <int — count of assistant turns in orchestrator transcript at dispatch>,
+#       "started_at": "<ISO-8601>" }
+#
+#   On SubagentStop fire the hook:
+#     1. Finds the newest .pending-task-*.json in the active sprint dir.
+#     2. Reads agent_type, work_item_id, turn_index from it.
+#     3. Computes token delta = sum of assistant turns at index >= turn_index in the transcript
+#        (NOT the cumulative whole-file sum — that was the SPRINT-05 double-count bug).
+#     4. Writes one JSONL row to token-ledger.jsonl with sentinel attribution.
+#     5. Deletes the sentinel atomically (mv → append → rm .processed-*).
+#
+#   If no sentinel exists: falls back to legacy transcript-grep for agent_type/work_item_id
+#   and computes the full-transcript delta (single-fire: no prior rows to double-count).
+#   Fail-silent on missing sentinel — never block a subagent stop (exit 0 always).
+#
+# ── Active sprint detection ────────────────────────────────────────────────────
+#
 #   Primary  : .cleargate/sprint-runs/.active sentinel file (one line: "SPRINT-NN")
 #              Orchestrator writes this at sprint kickoff, removes/updates at close.
 #   Fallback : .cleargate/sprint-runs/_off-sprint/token-ledger.jsonl
 #              When no .active sentinel exists, writes still get captured but
-#              tagged off-sprint instead of misrouting to a stale sprint dir.
+#              tagged _off-sprint instead of misrouting to a stale sprint dir.
 #   (Removed): the old `ls -td sprint-runs/*/ | head -1` mtime heuristic — it
 #              misrouted SPRINT-04 firings to SPRINT-03 because ledger appends
 #              themselves bumped SPRINT-03's mtime. See REPORT.md SPRINT-04.
 #
-# Work-item ID detection (GENERALIZED 2026-04-19 STORY-008-04, SCOPED 2026-04-26 BUG-010):
+# ── Work-item ID detection (legacy / no-sentinel path) ────────────────────────
+#
 #   Primary  : first user message in the transcript — that's the orchestrator's
 #              dispatch prompt, which by agent convention starts with
 #              `STORY=NNN-NN`, `PROPOSAL-NNN`, `EPIC-NNN`, `CR-NNN`, or `BUG-NNN`.
-#   Scoping  : look ONLY at lines whose FIRST CHARACTER matches the dispatch-marker
-#              pattern (line-anchored). The SessionStart hook emits a "blocked items"
-#              reminder that lists work-item IDs in prose/bullets — those lines start
-#              with "- " or whitespace, never with the marker prefix. Scanning the full
-#              content caused BUG-010: all SPRINT-14 rows tagged BUG-002 (first item in
-#              the reminder list). Fix: join content with \n, split, filter line-starts.
-#   Pattern  : ^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9]...
-#              PROP-NNN is normalised to PROPOSAL-NNN after match (BUG-009, 2026-04-26)
-#   Tie-break: when multiple dispatch-marker lines appear in the first user message,
-#              the FIRST line wins (deterministic; orchestrator puts the marker first).
-#   Fallback : grep first line-start match anywhere in the transcript.
+#   Pattern  : (STORY|PROPOSAL|EPIC|CR|BUG)[-=]?[0-9]+(-[0-9]+)?
+#   Fallback : grep first match anywhere in the transcript.
 #   story_id : populated only when the match is a STORY-* (backward compat).
 #   work_item_id: always populated when detection succeeds; equals story_id for STORY items.
 #   (Removed): grep-first-anywhere as PRIMARY — it picked up SPRINT-05 mentions
@@ -41,6 +56,11 @@
 
 set -u
 
+# CR-026: SessionStart blocked-items banner poisons transcript-grep (BUG-024 §3.1 Defect 2).
+# Skip-pattern: any line starting with "<N> items? blocked: " is the SessionStart banner.
+# Applied in the legacy work-item ID resolution block below via sed filtering.
+BANNER_SKIP_RE='^[0-9]+ items? blocked: '
+
 REPO_ROOT="${ORCHESTRATOR_PROJECT_DIR:-${CLAUDE_PROJECT_DIR}}"
 LOG_DIR="${REPO_ROOT}/.cleargate/hook-log"
 mkdir -p "${LOG_DIR}"
@@ -78,85 +98,187 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
   fi
   LEDGER="${SPRINT_DIR}/token-ledger.jsonl"
 
-  # --- walk transcript, sum usage across all assistant turns in this subagent run ---
-  USAGE_JSON="$(jq -cs '
-    map(select(.type == "assistant" and .message.usage))
-    | (map(.message.usage.input_tokens // 0)                     | add) as $in
-    | (map(.message.usage.output_tokens // 0)                    | add) as $out
-    | (map(.message.usage.cache_creation_input_tokens // 0)      | add) as $cc
-    | (map(.message.usage.cache_read_input_tokens // 0)          | add) as $cr
-    | (map(.message.model) | unique | map(select(. != null)) | join(","))     as $models
-    | (length)                                                   as $turns
-    | {input: $in, output: $out, cache_creation: $cc, cache_read: $cr, model: $models, turns: $turns}
-  ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+  # --- dispatch-marker attribution (CR-016 + CR-026, highest priority) ---
+  # The PreToolUse:Task hook (pre-tool-use-task.sh, CR-026) auto-writes:
+  #   .cleargate/sprint-runs/<sprint>/.dispatch-<ts>-<pid>-<rand>.json
+  # with { work_item_id, agent_type, spawned_at, session_id, writer }.
+  # Reading this file (if present) gives accurate attribution; falls back to the
+  # per-task pending-task sentinel (second priority) and transcript-scan (third).
+  #
+  # CR-026 Defect 1 fix — path-B (newest-file lookup):
+  # The old lookup keyed on the subagent's session_id from the SubagentStop payload,
+  # which is the *subagent's* session ID, never the orchestrator's. This caused 100%
+  # lookup failure since SPRINT-15 (BUG-024 §3.1 Defect 1). We now use newest-file
+  # lookup (ls -t) — atomic with the existing mv→.processed-$$ rename pattern.
+  # See CR-026 M3 plan §"Open Question Q1 resolution — path-A vs path-B".
+  #
+  # Atomicity: rename to .processed-$$ before reading, then delete post-row-write.
+  # This prevents stale dispatch files from leaking attribution to a later subagent.
+  SENTINEL_AGENT_TYPE=""
+  SENTINEL_WORK_ITEM_ID=""
+
+  # CR-026: newest-file lookup (path-B) — replaces session-id-keyed lookup.
+  DISPATCH_FILE="$(ls -t "${SPRINT_DIR}"/.dispatch-*.json 2>/dev/null | head -1)"
+  if [[ -n "${DISPATCH_FILE}" && -f "${DISPATCH_FILE}" ]]; then
+    DISPATCH_PROCESSED="${DISPATCH_FILE%.json}.processed-$$"
+    if mv "${DISPATCH_FILE}" "${DISPATCH_PROCESSED}" 2>/dev/null; then
+      DISPATCH_JSON="$(cat "${DISPATCH_PROCESSED}" 2>/dev/null)"
+      DISPATCH_AGENT="$(printf '%s' "${DISPATCH_JSON}" | jq -r '.agent_type // empty' 2>/dev/null)"
+      DISPATCH_WORK_ITEM="$(printf '%s' "${DISPATCH_JSON}" | jq -r '.work_item_id // empty' 2>/dev/null)"
+      if [[ -n "${DISPATCH_AGENT}" && -n "${DISPATCH_WORK_ITEM}" ]]; then
+        SENTINEL_AGENT_TYPE="${DISPATCH_AGENT}"
+        SENTINEL_WORK_ITEM_ID="${DISPATCH_WORK_ITEM}"
+        printf '[%s] dispatch-marker: session=%s work_item=%s agent=%s\n' \
+          "$(date -u +%FT%TZ)" "${SESSION_ID}" "${SENTINEL_WORK_ITEM_ID}" "${SENTINEL_AGENT_TYPE}" >> "${HOOK_LOG}"
+      else
+        printf '[%s] warn: dispatch file malformed or missing fields, falling back: %s\n' \
+          "$(date -u +%FT%TZ)" "${DISPATCH_PROCESSED}" >> "${HOOK_LOG}"
+      fi
+    else
+      printf '[%s] warn: could not rename dispatch file %s (race?), skipping\n' \
+        "$(date -u +%FT%TZ)" "${DISPATCH_FILE}" >> "${HOOK_LOG}"
+    fi
+  fi
+  # DISPATCH_PROCESSED is deleted after row-write (see "delete processed dispatch" block below).
+
+  # --- per-task sentinel: find newest .pending-task-*.json in sprint dir ---
+  # Second-priority fallback when dispatch-marker is absent or malformed.
+  # When dispatch-marker already populated SENTINEL_AGENT_TYPE + SENTINEL_WORK_ITEM_ID,
+  # still read the pending-task sentinel to get turn_index + started_at for delta accounting.
+  SENTINEL_FILE=""
+  SENTINEL_TURN_INDEX=0
+  SENTINEL_STARTED_AT=""
+  # Preserve SENTINEL_AGENT_TYPE / SENTINEL_WORK_ITEM_ID from dispatch block above.
+
+  if [[ -d "${SPRINT_DIR}" ]]; then
+    # Find newest pending-task sentinel (ls -t sorts newest first)
+    SENTINEL_FILE="$(ls -t "${SPRINT_DIR}"/.pending-task-*.json 2>/dev/null | head -1)"
+  fi
+
+  if [[ -n "${SENTINEL_FILE}" && -f "${SENTINEL_FILE}" ]]; then
+    SENTINEL_JSON="$(cat "${SENTINEL_FILE}" 2>/dev/null)"
+    # Only use attribution from pending-task if dispatch-marker did not already provide it.
+    if [[ -z "${SENTINEL_AGENT_TYPE}" ]]; then
+      SENTINEL_AGENT_TYPE="$(printf '%s' "${SENTINEL_JSON}" | jq -r '.agent_type // empty' 2>/dev/null)"
+    fi
+    if [[ -z "${SENTINEL_WORK_ITEM_ID}" ]]; then
+      SENTINEL_WORK_ITEM_ID="$(printf '%s' "${SENTINEL_JSON}" | jq -r '.work_item_id // empty' 2>/dev/null)"
+    fi
+    SENTINEL_TURN_INDEX="$(printf '%s' "${SENTINEL_JSON}" | jq -r '.turn_index // 0' 2>/dev/null)"
+    SENTINEL_STARTED_AT="$(printf '%s' "${SENTINEL_JSON}" | jq -r '.started_at // empty' 2>/dev/null)"
+    printf '[%s] found sentinel=%s agent=%s work_item=%s turn_index=%s\n' \
+      "$(date -u +%FT%TZ)" "${SENTINEL_FILE}" "${SENTINEL_AGENT_TYPE}" "${SENTINEL_WORK_ITEM_ID}" "${SENTINEL_TURN_INDEX}" >> "${HOOK_LOG}"
+  fi
+
+  # --- compute token usage ---
+  # DELTA MODEL (per-task sentinel path): slice transcript from turn_index forward.
+  # CUMULATIVE GUARD (no-sentinel path): use entire transcript — single-fire so no double-count.
+  #
+  # turn_index counts assistant turns (0-based). We select assistant turns, skip the first
+  # turn_index of them, then sum the remainder. This isolates tokens attributable to this subagent run.
+  if [[ -n "${SENTINEL_FILE}" && -f "${SENTINEL_FILE}" && -n "${SENTINEL_AGENT_TYPE}" ]]; then
+    # Delta model: slice from turn_index
+    USAGE_JSON="$(jq -cs --argjson idx "${SENTINEL_TURN_INDEX}" '
+      [ .[] | select(.type == "assistant" and .message.usage) ]
+      | .[$idx:]
+      | (map(.message.usage.input_tokens // 0)                     | add // 0) as $in
+      | (map(.message.usage.output_tokens // 0)                    | add // 0) as $out
+      | (map(.message.usage.cache_creation_input_tokens // 0)      | add // 0) as $cc
+      | (map(.message.usage.cache_read_input_tokens // 0)          | add // 0) as $cr
+      | (map(.message.model) | unique | map(select(. != null)) | join(","))     as $models
+      | (length)                                                   as $turns
+      | {input: $in, output: $out, cache_creation: $cc, cache_read: $cr, model: $models, turns: $turns}
+    ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+  else
+    # No sentinel: sum all assistant turns (full transcript — first fire, no prior rows to double-count)
+    USAGE_JSON="$(jq -cs '
+      map(select(.type == "assistant" and .message.usage))
+      | (map(.message.usage.input_tokens // 0)                     | add // 0) as $in
+      | (map(.message.usage.output_tokens // 0)                    | add // 0) as $out
+      | (map(.message.usage.cache_creation_input_tokens // 0)      | add // 0) as $cc
+      | (map(.message.usage.cache_read_input_tokens // 0)          | add // 0) as $cr
+      | (map(.message.model) | unique | map(select(. != null)) | join(","))     as $models
+      | (length)                                                   as $turns
+      | {input: $in, output: $out, cache_creation: $cc, cache_read: $cr, model: $models, turns: $turns}
+    ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+  fi
 
   if [[ -z "${USAGE_JSON}" || "${USAGE_JSON}" == "null" ]]; then
     printf '[%s] could not parse usage from %s\n' "$(date -u +%FT%TZ)" "${TRANSCRIPT_PATH}" >> "${HOOK_LOG}"
     exit 0
   fi
 
-  # --- detect agent_type ---
-  # Subagent transcripts contain `subagent_type` in the parent's tool invocation.
-  # Best-effort extraction; falls back to grepping role markers in the transcript body.
-  AGENT_TYPE="$(jq -rs '
-    [.[] | select(.type == "user") | .message.content]
-    | tostring
-    | capture("subagent_type[\"\\s:=]+(?<t>[a-zA-Z0-9_-]+)"; "g")?.t
-    // "unknown"
-  ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
-  [[ -z "${AGENT_TYPE}" || "${AGENT_TYPE}" == "null" ]] && AGENT_TYPE="unknown"
-
-  if [[ "${AGENT_TYPE}" == "unknown" ]]; then
-    for role in architect developer qa reporter; do
-      if grep -qiE "\\b${role}\\b agent|role: ${role}|you are the ${role}" "${TRANSCRIPT_PATH}" 2>/dev/null; then
-        AGENT_TYPE="${role}"
-        break
-      fi
-    done
+  # --- resolve agent_type and work_item_id ---
+  # Sentinel takes precedence; fall back to legacy transcript-grep when no sentinel.
+  AGENT_TYPE="${SENTINEL_AGENT_TYPE}"
+  WORK_ITEM_ID="${SENTINEL_WORK_ITEM_ID}"
+
+  if [[ -z "${AGENT_TYPE}" ]]; then
+    # Legacy: grep subagent_type from user messages, then role markers
+    AGENT_TYPE="$(jq -rs '
+      [.[] | select(.type == "user") | .message.content]
+      | tostring
+      | capture("subagent_type[\"\\s:=]+(?<t>[a-zA-Z0-9_-]+)"; "g")?.t
+      // "unknown"
+    ' "${TRANSCRIPT_PATH}" 2>/dev/null)"
+    [[ -z "${AGENT_TYPE}" || "${AGENT_TYPE}" == "null" ]] && AGENT_TYPE="unknown"
+
+    if [[ "${AGENT_TYPE}" == "unknown" ]]; then
+      for role in architect developer qa reporter cleargate-wiki-contradict; do
+        if grep -qiE "\\b${role}\\b agent|role: ${role}|you are the ${role}" "${TRANSCRIPT_PATH}" 2>/dev/null; then
+          AGENT_TYPE="${role}"
+          break
+        fi
+      done
+    fi
   fi
 
-  # --- detect work_item_id (PRIMARY: first user message; FALLBACK: anywhere-grep) ---
-  # Orchestrator convention (.claude/agents/developer.md): the FIRST LINE of the
-  # dispatch prompt is `STORY=NNN-NN` (or CR=NNN, BUG=NNN, EPIC=NNN, PROPOSAL=NNN,
-  # PROP=NNN). The SessionStart hook injects a "blocked items" reminder whose lines
-  # start with "- " or whitespace — never with the marker prefix. We therefore
-  # ONLY match lines whose first character is the start of the marker (line-anchored).
-  #
-  # BUG-010 (2026-04-26): joined with " " (space) before — scan() found BUG-002 from
-  # the reminder text. Fix: join with "\n" so line-anchored regex works.
-  #
-  # Pattern covers: STORY-NNN-NN, PROPOSAL-NNN, EPIC-NNN, CR-NNN, BUG-NNN
-  # (and = separator variants like STORY=008-04)
-  # Tie-break: first line matching the anchor wins (orchestrator puts marker first).
-  WORK_ITEM_RAW="$(jq -rs '
-    [.[] | select(.type == "user")] | .[0].message.content
-    | if type == "array" then map(.text? // "") | join("\n") else (. // "") end
-    | tostring
-    | split("\n")
-    | map(select(test("^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9]")))
-    | .[0] // ""
-    | capture("^(?<kind>STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=](?<id>[0-9]+(-[0-9]+)?)")
-    | (.kind + "-" + .id)
-  ' "${TRANSCRIPT_PATH}" 2>/dev/null | head -1)"
-
-  if [[ -n "${WORK_ITEM_RAW}" && "${WORK_ITEM_RAW}" != "null" && "${WORK_ITEM_RAW}" != "-" ]]; then
-    # Normalize: replace any = separator with - in the result
-    # Then normalize PROP-NNN → PROPOSAL-NNN (canonical form matches wiki/proposals/PROPOSAL-NNN.md filenames)
-    # BUG-009 (2026-04-26): PROP↔PROPOSAL normalization — PRESERVED BY BUG-010.
-    WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/')"
-  else
-    # Fallback: grep for line-start dispatch markers anywhere in the transcript.
-    # Line-anchored (^) so that "- BUG-002:" reminder bullet lines are not matched —
-    # only lines whose first character starts the marker prefix.
-    # BUG-009 normalization preserved: sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/'
-    WORK_ITEM_ID="$(grep -oE '^(STORY|PROPOSAL|PROP|EPIC|CR|BUG)[-=][0-9][0-9]*(-[0-9]+)?' "${TRANSCRIPT_PATH}" 2>/dev/null \
-      | head -1 \
-      | sed 's/=/-/g' | sed 's/^PROP-/PROPOSAL-/')"
-    if [[ -n "${WORK_ITEM_ID}" ]]; then
-      printf '[%s] work_item_id fallback grep: %s\n' "$(date -u +%FT%TZ)" "${WORK_ITEM_ID}" >> "${HOOK_LOG}"
+  if [[ -z "${WORK_ITEM_ID}" ]]; then
+    # Legacy: detect work_item_id (PRIMARY: first user message; FALLBACK: anywhere-grep)
+    #
+    # CR-026: banner-skip applied before jq scan (BUG-024 §3.1 Defect 2).
+    # The SessionStart hook emits a banner line of the form:
+    #   "N items blocked: BUG-004: ..."
+    # This line poisons transcript-grep by matching the work-item regex first.
+    # We skip it via select(. | test(BANNER_SKIP_RE) | not) in the jq pipeline.
+    # BANNER_SKIP_RE is defined near the top of this script.
+    WORK_ITEM_RAW="$(jq -rs --arg banner_re "${BANNER_SKIP_RE}" '
+      [.[] | select(.type == "user")]
+      | [.[] | select(
+          (.message.content | if type == "array"
+            then map(.text? // "") | join(" ")
+            else (. // "") end
+          ) | test($banner_re) | not
+        )]
+      | .[0].message.content
+      | if type == "array" then map(.text? // "") | join(" ") else (. // "") end
+      | tostring
+      | scan("(STORY|PROPOSAL|EPIC|CR|BUG|HOTFIX)[-=]?([0-9]+(-[0-9]+)?)") | .[0:2] | join("-")
+    ' "${TRANSCRIPT_PATH}" 2>/dev/null | head -1)"
+
+    if [[ -n "${WORK_ITEM_RAW}" && "${WORK_ITEM_RAW}" != "null" && "${WORK_ITEM_RAW}" != "-" ]]; then
+      WORK_ITEM_ID="$(printf '%s' "${WORK_ITEM_RAW}" | sed 's/=/-/g')"
+    else
+      # CR-026: fallback grep also applies banner-skip via sed filter.
+      WORK_ITEM_ID="$(sed -E "/${BANNER_SKIP_RE}/d" "${TRANSCRIPT_PATH}" 2>/dev/null \
+        | grep -oE '(STORY|PROPOSAL|EPIC|CR|BUG|HOTFIX)[-=]?[0-9]+(-[0-9]+)?' \
+        | head -1 \
+        | sed 's/=/-/g')"
+      if [[ -n "${WORK_ITEM_ID}" ]]; then
+        printf '[%s] work_item_id fallback grep: %s\n' "$(date -u +%FT%TZ)" "${WORK_ITEM_ID}" >> "${HOOK_LOG}"
+      fi
+    fi
+    [[ -z "${WORK_ITEM_ID}" ]] && WORK_ITEM_ID=""
+
+    # Legacy fallback: if no work_item_id found at all, fall back to old grep for story_id only
+    if [[ -z "${WORK_ITEM_ID}" ]]; then
+      STORY_ID_LEGACY="$(grep -oE 'STORY[-=]?[0-9]{3}-[0-9]{2}' "${TRANSCRIPT_PATH}" 2>/dev/null \
+        | head -1 \
+        | sed -E 's/STORY[-=]?([0-9]{3}-[0-9]{2})/STORY-\1/')"
+      [[ -z "${STORY_ID_LEGACY}" ]] && STORY_ID_LEGACY="none"
+      WORK_ITEM_ID="${STORY_ID_LEGACY}"
     fi
   fi
-  [[ -z "${WORK_ITEM_ID}" ]] && WORK_ITEM_ID=""
 
   # story_id is populated only when the work item is a STORY-* (backward compat)
   STORY_ID=""
@@ -164,17 +286,97 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
     STORY_ID="${WORK_ITEM_ID}"
   fi
 
-  # Legacy fallback: if no work_item_id found at all, fall back to old grep for story_id only
-  if [[ -z "${WORK_ITEM_ID}" ]]; then
-    STORY_ID="$(grep -oE 'STORY[-=]?[0-9]{3}-[0-9]{2}' "${TRANSCRIPT_PATH}" 2>/dev/null \
-      | head -1 \
-      | sed -E 's/STORY[-=]?([0-9]{3}-[0-9]{2})/STORY-\1/')"
-    [[ -z "${STORY_ID}" ]] && STORY_ID="none"
-    WORK_ITEM_ID="${STORY_ID}"
+  # --- atomic sentinel deletion (mv → append → rm) ---
+  PROCESSED_FILE=""
+  if [[ -n "${SENTINEL_FILE}" && -f "${SENTINEL_FILE}" ]]; then
+    PROCESSED_FILE="${SENTINEL_FILE%.json}.processed-$$"
+    if ! mv "${SENTINEL_FILE}" "${PROCESSED_FILE}" 2>/dev/null; then
+      # mv failed (race condition or permissions): proceed without deletion
+      PROCESSED_FILE=""
+      printf '[%s] warn: could not mv sentinel %s\n' "$(date -u +%FT%TZ)" "${SENTINEL_FILE}" >> "${HOOK_LOG}"
+    fi
+  fi
+
+  # --- per-turn delta math (CR-018) ---
+  # USAGE_JSON (computed above) is the intra-fire cumulative session total from the transcript.
+  # We maintain .session-totals.json keyed by session_id with the last-known cumulative totals.
+  # Cross-fire delta = current_session_total − prior_session_total.
+  # For the first fire of a session, delta == session_total.
+  #
+  # Atomic update via mktemp + mv (POSIX rename is atomic on the same filesystem).
+  # Concurrent-fire safety: two worktree SubagentStop fires may race. The atomic rename
+  # ensures one writer wins; the other sees the updated file on its next read.
+  SESSION_TOTALS_FILE="${SPRINT_DIR}/.session-totals.json"
+
+  # Read current session totals (or empty object if file absent)
+  PRIOR_SESSION_JSON="{}"
+  if [[ -f "${SESSION_TOTALS_FILE}" ]]; then
+    PRIOR_SESSION_JSON="$(cat "${SESSION_TOTALS_FILE}" 2>/dev/null || printf '{}')"
+    [[ -z "${PRIOR_SESSION_JSON}" ]] && PRIOR_SESSION_JSON="{}"
   fi
 
-  # --- assemble ledger row ---
+  # Compute current intra-fire totals from USAGE_JSON
+  CURRENT_IN="$(printf '%s' "${USAGE_JSON}" | jq -r '.input // 0')"
+  CURRENT_OUT="$(printf '%s' "${USAGE_JSON}" | jq -r '.output // 0')"
+  CURRENT_CC="$(printf '%s' "${USAGE_JSON}" | jq -r '.cache_creation // 0')"
+  CURRENT_CR="$(printf '%s' "${USAGE_JSON}" | jq -r '.cache_read // 0')"
+  CURRENT_MODEL="$(printf '%s' "${USAGE_JSON}" | jq -r '.model // ""')"
+  CURRENT_TURNS="$(printf '%s' "${USAGE_JSON}" | jq -r '.turns // 0')"
+
+  # Look up prior totals for this session_id
+  PRIOR_IN="$(printf '%s' "${PRIOR_SESSION_JSON}" | jq -r --arg sid "${SESSION_ID}" '.[$sid].input // 0' 2>/dev/null || printf '0')"
+  PRIOR_OUT="$(printf '%s' "${PRIOR_SESSION_JSON}" | jq -r --arg sid "${SESSION_ID}" '.[$sid].output // 0' 2>/dev/null || printf '0')"
+  PRIOR_CC="$(printf '%s' "${PRIOR_SESSION_JSON}" | jq -r --arg sid "${SESSION_ID}" '.[$sid].cache_creation // 0' 2>/dev/null || printf '0')"
+  PRIOR_CR="$(printf '%s' "${PRIOR_SESSION_JSON}" | jq -r --arg sid "${SESSION_ID}" '.[$sid].cache_read // 0' 2>/dev/null || printf '0')"
+
+  # Compute delta = current − prior (floor at 0 to guard against transcript-reread edge cases)
+  DELTA_IN=$(( CURRENT_IN - PRIOR_IN ))
+  DELTA_OUT=$(( CURRENT_OUT - PRIOR_OUT ))
+  DELTA_CC=$(( CURRENT_CC - PRIOR_CC ))
+  DELTA_CR=$(( CURRENT_CR - PRIOR_CR ))
+  [[ "${DELTA_IN}" -lt 0 ]] && DELTA_IN=0
+  [[ "${DELTA_OUT}" -lt 0 ]] && DELTA_OUT=0
+  [[ "${DELTA_CC}" -lt 0 ]] && DELTA_CC=0
+  [[ "${DELTA_CR}" -lt 0 ]] && DELTA_CR=0
+
+  # Build delta and session_total JSON blocks
+  DELTA_JSON="$(jq -cn \
+    --argjson in "${DELTA_IN}" \
+    --argjson out "${DELTA_OUT}" \
+    --argjson cc "${DELTA_CC}" \
+    --argjson cr "${DELTA_CR}" \
+    '{input: $in, output: $out, cache_creation: $cc, cache_read: $cr}')"
+
+  SESSION_TOTAL_JSON="$(jq -cn \
+    --argjson in "${CURRENT_IN}" \
+    --argjson out "${CURRENT_OUT}" \
+    --argjson cc "${CURRENT_CC}" \
+    --argjson cr "${CURRENT_CR}" \
+    '{input: $in, output: $out, cache_creation: $cc, cache_read: $cr}')"
+
+  # Atomically update .session-totals.json with new totals for this session_id
   TS="$(date -u +%FT%TZ)"
+  NEW_SESSION_TOTALS="$(printf '%s' "${PRIOR_SESSION_JSON}" | jq -c \
+    --arg sid "${SESSION_ID}" \
+    --argjson in "${CURRENT_IN}" \
+    --argjson out "${CURRENT_OUT}" \
+    --argjson cc "${CURRENT_CC}" \
+    --argjson cr "${CURRENT_CR}" \
+    --arg ts "${TS}" \
+    --argjson ti "${SENTINEL_TURN_INDEX}" \
+    '.[$sid] = {input: $in, output: $out, cache_creation: $cc, cache_read: $cr, last_ts: $ts, last_turn_index: $ti}' \
+    2>/dev/null)"
+
+  if [[ -n "${NEW_SESSION_TOTALS}" ]]; then
+    SESSION_TOTALS_TMP="$(mktemp "${SESSION_TOTALS_FILE}.tmp.XXXXXX" 2>/dev/null)"
+    if [[ -n "${SESSION_TOTALS_TMP}" ]]; then
+      printf '%s\n' "${NEW_SESSION_TOTALS}" > "${SESSION_TOTALS_TMP}"
+      mv "${SESSION_TOTALS_TMP}" "${SESSION_TOTALS_FILE}" 2>/dev/null || \
+        printf '[%s] warn: could not atomic-rename session-totals\n' "${TS}" >> "${HOOK_LOG}"
+    fi
+  fi
+
+  # --- assemble ledger row (v2 schema: delta + session_total replace flat input/output/cache_*) ---
   ROW="$(jq -cn \
     --arg ts "${TS}" \
     --arg agent "${AGENT_TYPE}" \
@@ -183,15 +385,31 @@ ACTIVE_SENTINEL="${REPO_ROOT}/.cleargate/sprint-runs/.active"
     --arg session "${SESSION_ID}" \
     --arg transcript "${TRANSCRIPT_PATH}" \
     --arg sprint "${SPRINT_ID}" \
-    --argjson usage "${USAGE_JSON}" \
-    '{ts: $ts, sprint_id: $sprint, agent_type: $agent, story_id: $story, work_item_id: $work_item, session_id: $session, transcript: $transcript} + $usage')"
+    --arg sentinel_started_at "${SENTINEL_STARTED_AT}" \
+    --argjson turn_index "${SENTINEL_TURN_INDEX}" \
+    --argjson delta "${DELTA_JSON}" \
+    --argjson session_total "${SESSION_TOTAL_JSON}" \
+    --arg model "${CURRENT_MODEL}" \
+    --argjson turns "${CURRENT_TURNS}" \
+    '{ts: $ts, sprint_id: $sprint, story_id: $story, work_item_id: $work_item, agent_type: $agent, session_id: $session, transcript: $transcript, sentinel_started_at: $sentinel_started_at, delta_from_turn: $turn_index, delta: $delta, session_total: $session_total, model: $model, turns: $turns}')"
 
   printf '%s\n' "${ROW}" >> "${LEDGER}"
-  printf '[%s] wrote row: sprint=%s agent=%s work_item=%s story=%s tokens=in:%s/out:%s\n' \
+  printf '[%s] wrote row: sprint=%s agent=%s work_item=%s story=%s delta=in:%s/out:%s session_total=in:%s/out:%s delta_from=%s\n' \
     "${TS}" "${SPRINT_ID}" "${AGENT_TYPE}" "${WORK_ITEM_ID}" "${STORY_ID}" \
-    "$(printf '%s' "${USAGE_JSON}" | jq -r '.input')" \
-    "$(printf '%s' "${USAGE_JSON}" | jq -r '.output')" \
+    "${DELTA_IN}" "${DELTA_OUT}" \
+    "${CURRENT_IN}" "${CURRENT_OUT}" \
+    "${SENTINEL_TURN_INDEX}" \
     >> "${HOOK_LOG}"
+
+  # --- delete processed sentinel ---
+  if [[ -n "${PROCESSED_FILE}" && -f "${PROCESSED_FILE}" ]]; then
+    rm -f "${PROCESSED_FILE}"
+  fi
+
+  # --- delete processed dispatch file ---
+  if [[ -n "${DISPATCH_PROCESSED:-}" && -f "${DISPATCH_PROCESSED}" ]]; then
+    rm -f "${DISPATCH_PROCESSED}"
+  fi
 } 2>> "${HOOK_LOG}"
 
 exit 0

package/templates/cleargate-planning/.claude/settings.json

@@ -17,6 +17,10 @@
           {
             "type": "command",
             "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pending-task-sentinel.sh"
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-tool-use-task.sh"
           }
         ]
       },