@kontourai/flow-agents 3.9.0 → 3.10.0

package/scripts/telemetry/lib/transport.sh

@@ -2,6 +2,9 @@
 # transport.sh — Dual-channel telemetry transport
 
 source "${TELEMETRY_DIR}/lib/redact.sh"
+# Shared usage.model / numeric-bound validation constants (security review
+# HIGH + LOW findings) -- single source, also used by usage.sh's extractor.
+source "${TELEMETRY_DIR}/lib/usage_model_guard.sh"
 
 console_telemetry_endpoint_url() {
   if [[ -n "${CONSOLE_TELEMETRY_ENDPOINT_URL:-}" ]]; then
@@ -178,12 +181,80 @@ console_project_label() {
   printf '%s' "$label"
 }
 
+# Defense-in-depth sanitize backstop (#568 slice 1 security review, MEDIUM,
+# hardened per HIGH + LOW follow-up findings): nulls any
+# usage.{input_tokens,output_tokens,cache_creation_input_tokens,
+# cache_read_input_tokens,estimated_cost_usd} that isn't a JSON number within
+# [USAGE_NUMERIC_MIN, USAGE_NUMERIC_MAX] (negative/absurd-magnitude values are
+# as untrusted as a wrong-typed one), and bounds/validates usage.model against
+# the SAME shared vendor-prefix allowlist (USAGE_MODEL_REGEX/
+# USAGE_MODEL_MAX_LEN, from usage_model_guard.sh) usage_last_turn_usage
+# enforces at extraction time -- a charset-only check here would be, and
+# previously was, a strict superset of secret/credential shapes (API keys,
+# JWTs) that a regression in the primary extractor could otherwise relay
+# verbatim. FAILS CLOSED: if `.usage` is present but is not a JSON object (a
+# raw string/number/array -- e.g. a future caller populating it wrong), the
+# whole `.usage` is nulled rather than left unsanitized (a naive
+# `.usage? != null` + `?`-chained field check on a non-object silently
+# produces NO jq output at all, which the caller would then treat as "sanitize
+# failed" and fall through to the ORIGINAL unsanitized event -- exactly the
+# fail-OPEN bug this branch exists to close). This exists so a FUTURE
+# extractor regression (a new caller populating .usage from a less-trusted
+# source, a refactor that drops a type/shape guard, etc.) can never again
+# relay an untyped/oversized/malformed/secret-shaped value to the console; it
+# is not the primary defense (usage_last_turn_usage already type-guards and
+# allowlists every field) but a last-resort net right before the POST. One jq
+# pass, no extra process spawned beyond the jq call already needed here.
+console_telemetry_sanitize_usage() {
+  local event="$1"
+  # FAIL CLOSED if the shared guard constants didn't resolve (e.g. a partial
+  # dist/ sync dropped usage_model_guard.sh): null .usage entirely rather than
+  # running a broken/empty jq that would return nothing and let the caller relay
+  # the ORIGINAL unsanitized event. Never fail open on a packaging defect.
+  if [[ -z "$USAGE_MODEL_REGEX" || -z "$USAGE_MODEL_MAX_LEN" || -z "$USAGE_NUMERIC_MIN" || -z "$USAGE_NUMERIC_MAX" ]]; then
+    printf '%s' "$event" | jq -c 'if has("usage") then .usage = null else . end'
+    return
+  fi
+  printf '%s' "$event" | jq -c \
+    --arg model_regex "$USAGE_MODEL_REGEX" \
+    --argjson model_max_len "$USAGE_MODEL_MAX_LEN" \
+    --argjson numeric_min "$USAGE_NUMERIC_MIN" \
+    --argjson numeric_max "$USAGE_NUMERIC_MAX" '
+    def bounded_number($v):
+      if ($v | type) == "number" and $v >= $numeric_min and $v <= $numeric_max then $v else null end;
+    if (.usage? == null) then .
+    elif ((.usage | type) != "object") then (.usage = null)
+    else
+      .usage.input_tokens = bounded_number(.usage.input_tokens?)
+      | .usage.output_tokens = bounded_number(.usage.output_tokens?)
+      | .usage.cache_creation_input_tokens = bounded_number(.usage.cache_creation_input_tokens?)
+      | .usage.cache_read_input_tokens = bounded_number(.usage.cache_read_input_tokens?)
+      | .usage.estimated_cost_usd = bounded_number(.usage.estimated_cost_usd?)
+      | .usage.model = (
+          if ((.usage.model? | type) == "string")
+             and ((.usage.model | length) <= $model_max_len)
+             and (.usage.model | test($model_regex))
+          then .usage.model
+          else null
+          end
+        )
+    end
+  ' 2>/dev/null
+}
+
 console_telemetry_emit() {
   local event="$1"
   local endpoint_url
   endpoint_url=$(console_telemetry_endpoint_url)
   [[ -z "$endpoint_url" ]] && return
 
+  # Sanitize backstop runs before anything else so labeling/redaction/POST all
+  # see the already-bounded event; a failed/empty sanitize pass (bad JSON)
+  # falls back to the original event unchanged (never blocks relay).
+  local sanitized_event
+  sanitized_event=$(console_telemetry_sanitize_usage "$event") || sanitized_event=""
+  [[ -n "$sanitized_event" ]] && event="$sanitized_event"
+
   # Attribution: stamp a coarse, path-free project label (see console_project_label) before redaction
   # so the console buckets by project consistently across developers. The full context.cwd is still
   # redacted below — only the label leaves the machine. Every substitution is `|| var=""`-guarded so

package/scripts/telemetry/lib/usage.sh

@@ -6,6 +6,9 @@ USAGE_LIB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 # Single-source pricing registry loader (local / remote / bundled).
 source "${USAGE_LIB_DIR}/pricing.sh"
+# Shared usage.model / numeric-bound validation constants (security review
+# HIGH + LOW findings) -- single source, also used by transport.sh's backstop.
+source "${USAGE_LIB_DIR}/usage_model_guard.sh"
 
 # Resolve model from agent-spec.json
 usage_get_model() {
@@ -89,6 +92,50 @@ usage_count_delegations() {
 # if the on-disk schema changes so drift is logged rather than silently zeroed.
 USAGE_TRANSCRIPT_SCHEMA="message.usage.input_tokens"
 
+# Bounded tail-read size for usage_last_turn_usage (per-tool-call join), in
+# bytes. Overridable via env for tuning; default 256 KiB is large enough to
+# reliably contain the most recent assistant usage block even with sizeable
+# tool-output content nearby, small enough to bound per-call latency (this
+# function runs once per tool call, unlike usage_parse_transcript which runs
+# once per session at stop).
+TELEMETRY_USAGE_TAIL_BYTES="${TELEMETRY_USAGE_TAIL_BYTES:-262144}"
+
+# Shared pricing/cache-multiplier formula — the ONE place the per-model cost
+# arithmetic is defined. Both usage_parse_transcript (whole-session aggregate,
+# at `stop`) and usage_last_turn_usage (single-turn, per tool call) prepend
+# this jq `def` to their program text and call price_one(...), rather than
+# each hand-copying the formula (see #356 shared-not-forked discipline in
+# transport.sh — a duplicated formula is exactly the kind of drift that
+# invites). Given a model id ($m), a token breakdown ($u — object with
+# input/output/cache_creation/cache_read keys), the resolved pricing registry
+# ($registry), whether it's usable ($has_registry), and a requested pricing
+# version ($version, empty string = registry's current_version), returns
+# {estimated_cost_usd, pricing_version} — both null when no registry/version
+# resolves (never invents a cost from unpriced data).
+USAGE_PRICE_ONE_JQ_DEF='
+def price_one($m; $u; $registry; $has_registry; $version):
+  ($has_registry and ($registry != null)) as $has_reg
+  | (if $has_reg then (if $version == "" then $registry.current_version else $version end) else null end) as $ver
+  | (if $has_reg and ($ver != null) then ($registry.versions[$ver]) else null end) as $p
+  | ($p != null) as $priced
+  | (if $priced then $p.cache_multipliers else null end) as $cm
+  | (if $priced then (($p.models[$m]) // $p.default) else null end) as $rate
+  | (if $priced then (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) else null end) as $billable
+  | {
+      estimated_cost_usd: (
+        if $priced then
+          $billable * (
+            ($u.input // 0)          * $rate.input
+            + ($u.output // 0)         * $rate.output
+            + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
+            + ($u.cache_read // 0)     * $rate.input * $cm.read
+          ) / 1000000
+        else null end
+      ),
+      pricing_version: (if $priced then $ver else null end)
+    };
+'
+
 # Append a one-line schema-drift warning (transcript carried usage data we could
 # not parse). Goes to TELEMETRY_DRIFT_LOG if set, else stderr. Never fatal.
 usage_log_drift() {
@@ -118,6 +165,54 @@ usage_log_debug() {
   fi
 }
 
+# Shared registry resolution (DRY fix, review finding MEDIUM/code): both
+# usage_parse_transcript and usage_last_turn_usage need {registry, has_registry}
+# before invoking price_one() -- resolve it in exactly one place instead of
+# hand-copying the resolve+validate block in each caller.
+#   $1 = name of the caller's variable to receive the registry JSON (or the
+#        literal string "null" when unavailable/unparseable)
+#   $2 = name of the caller's variable to receive has_registry ("true"/"false")
+#   $3 = mode: "" (default -- pricing_registry() may hit network/local/bundled
+#        sources, used by usage_parse_transcript's once-per-session stop path)
+#        | "cache_only" (never perform a network fetch -- see
+#        usage_last_turn_usage's per-tool-call latency/race note below; a
+#        cold/stale cache degrades straight to the bundled snapshot)
+#   $4 = optional log context (e.g. transcript path) for usage_log_debug parity
+#        with the pre-refactor per-caller messages
+usage_resolve_registry() {
+  local __usage_reg_var="$1" __usage_has_var="$2" __usage_mode="${3:-}" __usage_log_ctx="${4:-}"
+  # Double-underscore-prefixed locals throughout (matching this function's own
+  # parameter convention, code review LOW finding) to harden against a future
+  # third caller's variable-name collision -- these never leak into the
+  # caller's scope (output is returned only via printf -v into the caller's
+  # named variables above), but a plain `_registry`/`_has_registry` name is
+  # exactly the kind of generic local name a future edit could accidentally
+  # shadow.
+  local __registry __has_registry
+  if [[ "$__usage_mode" == "cache_only" ]]; then
+    __registry="$(TELEMETRY_PRICING_CACHE_ONLY=1 pricing_registry 2>/dev/null)"
+  else
+    __registry="$(pricing_registry 2>/dev/null)"
+  fi
+  if [[ $? -eq 0 && -n "$__registry" ]]; then
+    __has_registry=true
+  else
+    __has_registry=false
+    __registry='null'
+    [[ -n "$__usage_log_ctx" ]] && usage_log_debug "pricing registry unavailable (${__usage_log_ctx}) — extracting tokens without cost"
+  fi
+  # A non-empty registry can still be malformed (corrupt/truncated pricing.json,
+  # or a bad remote 200) — validate it parses before handing it to `jq -n
+  # --argjson`, which would otherwise abort the whole parse and discard tokens.
+  if [[ "$__has_registry" == true ]] && ! jq -e . >/dev/null 2>&1 <<<"$__registry"; then
+    __has_registry=false
+    __registry='null'
+    [[ -n "$__usage_log_ctx" ]] && usage_log_debug "pricing registry unparseable (${__usage_log_ctx}) — extracting tokens without cost"
+  fi
+  printf -v "$__usage_reg_var" '%s' "$__registry"
+  printf -v "$__usage_has_var" '%s' "$__has_registry"
+}
+
 usage_parse_transcript() {
   local transcript="$1" version="${2:-}"
   if [[ -z "$transcript" ]]; then
@@ -136,33 +231,17 @@ usage_parse_transcript() {
   # Pricing registry is best-effort: when unavailable, tokens are still
   # extracted below and only the cost fields degrade to null (defect #2 fix —
   # previously this hard-returned 1 here, discarding token extraction
-  # entirely whenever pricing_registry() failed).
+  # entirely whenever pricing_registry() failed). Resolution itself is shared
+  # with usage_last_turn_usage via usage_resolve_registry (DRY fix).
   local registry has_registry
-  registry="$(pricing_registry 2>/dev/null)"
-  if [[ $? -eq 0 && -n "$registry" ]]; then
-    has_registry=true
-  else
-    has_registry=false
-    registry='null'
-    usage_log_debug "pricing registry unavailable (${transcript}) — extracting tokens without cost"
-  fi
-  # A non-empty registry can still be malformed (corrupt/truncated pricing.json,
-  # or a bad remote 200) — validate it parses before handing it to `jq -n
-  # --argjson`, which would otherwise abort the whole parse and discard tokens
-  # (the exact intermittent-null-tokens defect this function exists to fix).
-  if [[ "$has_registry" == true ]] && ! jq -e . >/dev/null 2>&1 <<<"$registry"; then
-    has_registry=false
-    registry='null'
-    usage_log_debug "pricing registry unparseable (${transcript}) — extracting tokens without cost"
-  fi
+  usage_resolve_registry registry has_registry "" "$transcript"
 
   local out
-  out="$(jq -n --argjson registry "$registry" --argjson has_registry "$has_registry" --arg version "$version" '
+  out="$(jq -n --argjson registry "$registry" --argjson has_registry "$has_registry" --arg version "$version" "${USAGE_PRICE_ONE_JQ_DEF}"'
     ($has_registry and ($registry != null)) as $has_reg
     | (if $has_reg then (if $version == "" then $registry.current_version else $version end) else null end) as $ver
     | (if $has_reg and ($ver != null) then ($registry.versions[$ver]) else null end) as $p
     | ($p != null) as $priced
-    | (if $priced then $p.cache_multipliers else null end) as $cm
     | (reduce inputs as $l ({};
         ($l.message.usage) as $u
         | if $u then
@@ -175,24 +254,14 @@ usage_parse_transcript() {
     | ($agg | to_entries
         | map(
             .key as $m | .value as $u
-            | (if $priced then (($p.models[$m]) // $p.default) else null end) as $rate
-            | (if $priced then (if ([$m] | inside($p.zero_cost_models)) then 0 else 1 end) else null end) as $billable
+            | price_one($m; $u; $registry; $has_registry; $version) as $price
             | {
                 model: $m,
                 input_tokens: ($u.input // 0),
                 output_tokens: ($u.output // 0),
                 cache_creation_input_tokens: ($u.cache_creation // 0),
                 cache_read_input_tokens: ($u.cache_read // 0),
-                estimated_cost_usd: (
-                  if $priced then
-                    $billable * (
-                      ($u.input // 0)          * $rate.input
-                      + ($u.output // 0)         * $rate.output
-                      + ($u.cache_creation // 0) * $rate.input * $cm.write_5m
-                      + ($u.cache_read // 0)     * $rate.input * $cm.read
-                    ) / 1000000
-                  else null end
-                )
+                estimated_cost_usd: $price.estimated_cost_usd
               })) as $by_model
     | {
         by_model: $by_model,
@@ -228,3 +297,184 @@ usage_parse_transcript() {
 
   printf '%s\n' "$out"
 }
+
+# Bounded, single-turn usage extractor — the tool-event (preToolUse/
+# postToolUse) counterpart to usage_parse_transcript's whole-session
+# aggregate (used only at `stop`). This runs once per tool call, so unlike
+# usage_parse_transcript it MUST NOT scan the whole transcript: a large
+# session can fire hundreds of tool calls, and a full-file jq scan per call
+# would add real, cumulative latency to every tool invocation.
+#
+# Reads only the last TELEMETRY_USAGE_TAIL_BYTES bytes of the transcript,
+# drops the (possibly partial) first line of that tail window, and returns
+# the LAST well-formed `type=="assistant"` line with a `message.usage` object.
+# Because tool execution is synchronous — the CLI appends the requesting
+# assistant message (including its tool_use blocks) before firing PreToolUse
+# for each block, and no new assistant turn can be appended mid-tool-call —
+# that last assistant/usage entry at hook-fire time is exactly the turn that
+# produced this specific tool call, for both PreToolUse and PostToolUse of the
+# same call.
+#
+# Hardened line selection (security review findings CRITICAL/HIGH): the tail
+# window is parsed in `jq -R` RAW mode, one line at a time, with `fromjson?`
+# per line — a torn/malformed line ANYWHERE in the window (e.g. a concurrent
+# writer's partial trailing write, or noise before/after the real line) is
+# SKIPPED, never fatal, and never masks a real usage line elsewhere in the
+# window (previously a single malformed line anywhere in the tail aborted the
+# whole `jq -n` JSON-mode parse, silently discarding a present, findable usage
+# line). Every extracted field is independently type-guarded AND bound-checked
+# before it is ever emitted: a token/cost field is emitted ONLY if it is a
+# JSON number within [USAGE_NUMERIC_MIN, USAGE_NUMERIC_MAX] (never a string,
+# object, array, negative, or absurd magnitude like 1e308 — never
+# "0-as-fabrication" when the source type/range is wrong; see
+# usage_model_guard.sh). `model` is emitted ONLY if it is a string, <=
+# USAGE_MODEL_MAX_LEN chars, AND matches USAGE_MODEL_REGEX — a small,
+# case-insensitive VENDOR-PREFIX ALLOWLIST (claude/gpt/o<digit>/gemini/glm/
+# llama/mistral/deepseek/qwen/grok/command/codestral), NOT a bare charset
+# check (security review HIGH finding: a charset-only check like
+# `^[A-Za-z0-9._:-]+$` is a strict SUPERSET of common secret/credential
+# shapes — an Anthropic API key `sk-ant-api03-...`, an AWS key `AKIA...`, or a
+# JWT `eyJ...` all satisfy that charset and would pass through verbatim).
+# Anything that doesn't match the allowlist resolves to "unknown". This is
+# what stops a crafted transcript line (e.g. {"message":{"model":"<secret or
+# arbitrary text>","usage":{"input_tokens":"<arbitrary text>"}}}) from ever
+# landing a raw string in the emitted record (previously `// 0` /
+# `// "unknown"` copied a wrong-typed value through verbatim, which then
+# relayed to the console unredacted since usage.* isn't on the redact
+# deny-list). estimated_cost_usd/pricing_version are computed ONLY when every
+# token field for that turn is a valid, bounded number — a turn with any
+# invalid/out-of-range token field degrades to null cost too, never a cost
+# computed from partly-zeroed untrusted data; the computed cost itself is
+# then also bound-checked before being emitted (defense-in-depth against an
+# implausible pricing-registry rate).
+#
+# Prints a compact JSON object on success:
+#   {model, input_tokens, output_tokens, cache_creation_input_tokens,
+#    cache_read_input_tokens, estimated_cost_usd, pricing_version}
+# and returns 0. Prints nothing and returns 1 when the transcript is
+# missing/unreadable, jq is unavailable, or no assistant/usage line is found
+# within the tail window (e.g. transcript not Anthropic-message-shaped, or a
+# huge preceding blob pushed the last assistant entry outside the bound) —
+# the caller degrades to its own model-only/null fallback; this function
+# never invents a number. Reuses the exact pricing/cache-multiplier formula
+# usage_parse_transcript uses, via the shared USAGE_PRICE_ONE_JQ_DEF/
+# price_one() helper above (one source, two call sites), and the shared
+# usage_resolve_registry() registry-resolution helper (also one source, two
+# call sites — review finding MEDIUM/code DRY fix).
+#
+# Pricing resolution here is deliberately CACHE-ONLY (review finding
+# MEDIUM/code latency+race): this function runs once per tool call, so a
+# cold/stale local pricing cache must never trigger a blocking
+# `curl --max-time 5` (and race pricing.sh's fixed `${cache}.tmp` path)
+# per tool call. `usage_resolve_registry ... cache_only` skips the network
+# branch entirely; session.usage (usage_parse_transcript, once per session at
+# `stop`) remains the authoritative cost source and still resolves the
+# registry normally (network-eligible). A cold cache here just means
+# estimated_cost_usd/pricing_version are null for this tool event — tokens
+# still survive.
+usage_last_turn_usage() {
+  local transcript="$1" version="${2:-}"
+  if [[ -z "$transcript" ]]; then
+    usage_log_debug "usage_last_turn_usage: no usage — reason: empty transcript_path"
+    return 1
+  fi
+  if [[ ! -f "$transcript" || ! -r "$transcript" ]]; then
+    usage_log_debug "usage_last_turn_usage: no usage — reason: transcript file missing/unreadable (${transcript})"
+    return 1
+  fi
+  if ! command -v jq >/dev/null 2>&1; then
+    usage_log_debug "usage_last_turn_usage: no usage — reason: jq unavailable"
+    return 1
+  fi
+
+  local file_size
+  file_size="$(wc -c < "$transcript" 2>/dev/null | tr -d ' ')"
+  [[ "$file_size" =~ ^[0-9]+$ ]] || file_size=0
+
+  # Bounded tail-read: only the last N bytes when the file exceeds the bound,
+  # then drop the first (possibly partial/truncated-mid-JSON) line of that
+  # window. This is a cheap belt-and-suspenders trim, not a correctness
+  # requirement any more — the jq program below tolerates a malformed line
+  # anywhere in the window (see the hardened-parsing note above) — but there
+  # is no reason to hand jq a line we already know is certainly truncated.
+  local tail_text
+  if [[ "$file_size" -gt "$TELEMETRY_USAGE_TAIL_BYTES" ]]; then
+    tail_text="$(tail -c "$TELEMETRY_USAGE_TAIL_BYTES" "$transcript" 2>/dev/null | tail -n +2)"
+  else
+    tail_text="$(cat "$transcript" 2>/dev/null)"
+  fi
+  if [[ -z "$tail_text" ]]; then
+    usage_log_debug "usage_last_turn_usage: no usage — reason: empty tail window (${transcript})"
+    return 1
+  fi
+
+  # Pricing registry — cache-only (see function header): never a network
+  # fetch per tool call. Missing/unparseable registry degrades cost/
+  # pricing_version to null but never blocks token extraction.
+  local registry has_registry
+  usage_resolve_registry registry has_registry cache_only "$transcript"
+
+  local jq_program
+  jq_program="${USAGE_PRICE_ONE_JQ_DEF}"'
+    def bounded_number($v):
+      if ($v | type) == "number" and $v >= $numeric_min and $v <= $numeric_max then $v else null end;
+    (
+      [inputs]
+      | map(try fromjson catch null)
+      | map(select(. != null))
+      | map(select(
+          (.type? == "assistant")
+          and ((.message?.usage?) != null)
+          and ((.message.usage | type) == "object")
+        ))
+      | last
+    ) as $turn
+    | if $turn == null then empty else
+        ($turn.message.usage) as $raw
+        | (
+            (($turn.message.model?) | type) == "string"
+            and (($turn.message.model | length) <= $model_max_len)
+            and ($turn.message.model | test($model_regex))
+          ) as $model_valid
+        | (if $model_valid then $turn.message.model else "unknown" end) as $m
+        | bounded_number($raw.input_tokens?) as $input
+        | bounded_number($raw.output_tokens?) as $output
+        | bounded_number($raw.cache_creation_input_tokens?) as $cache_creation
+        | bounded_number($raw.cache_read_input_tokens?) as $cache_read
+        | ($input != null and $output != null and $cache_creation != null and $cache_read != null) as $tokens_all_valid
+        | (if $tokens_all_valid then
+             price_one($m; {input: $input, output: $output, cache_creation: $cache_creation, cache_read: $cache_read}; $registry; $has_registry; $version)
+           else
+             {estimated_cost_usd: null, pricing_version: null}
+           end) as $price
+        | bounded_number($price.estimated_cost_usd?) as $cost_bounded
+        | {
+            model: $m,
+            input_tokens: $input,
+            output_tokens: $output,
+            cache_creation_input_tokens: $cache_creation,
+            cache_read_input_tokens: $cache_read,
+            estimated_cost_usd: $cost_bounded,
+            pricing_version: $price.pricing_version
+          }
+      end
+  '
+
+  local out
+  out="$(jq -R -n -c \
+    --argjson registry "$registry" \
+    --argjson has_registry "$has_registry" \
+    --arg version "$version" \
+    --arg model_regex "$USAGE_MODEL_REGEX" \
+    --argjson model_max_len "$USAGE_MODEL_MAX_LEN" \
+    --argjson numeric_min "$USAGE_NUMERIC_MIN" \
+    --argjson numeric_max "$USAGE_NUMERIC_MAX" \
+    "$jq_program" <<<"$tail_text" 2>/dev/null)"
+
+  if [[ -z "$out" ]]; then
+    usage_log_debug "usage_last_turn_usage: no usage — reason: no assistant/usage entry in tail window (${transcript})"
+    return 1
+  fi
+
+  printf '%s\n' "$out"
+}

package/scripts/telemetry/lib/usage_model_guard.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# usage_model_guard.sh — shared usage.model/usage.numeric validation constants
+# (#568 slice 1 security review, HIGH + LOW findings).
+#
+# HIGH: a charset-only check (e.g. `^[A-Za-z0-9._:-]+$`, <=128 chars) is a
+# STRICT SUPERSET of common secret/credential shapes -- an Anthropic API key
+# (`sk-ant-api03-...`), an AWS access key (`AKIA...`), or a JWT (`eyJ...`,
+# often with an embedded email) all satisfy that charset and would pass
+# through verbatim into usage.model. A model id must instead match a small,
+# known VENDOR-PREFIX ALLOWLIST (case-insensitive) and stay under a much
+# tighter length bound. Sourced by BOTH usage.sh (the primary extractor,
+# usage_last_turn_usage) and transport.sh (the defense-in-depth backstop,
+# console_telemetry_sanitize_usage) so the pattern is defined in exactly ONE
+# place -- never hand-copied into two jq programs that could drift apart.
+#
+# LOW: a `type=="number"` check alone accepts negative and absurd-magnitude
+# values (e.g. -1, 1e308) as if they were real token counts / costs. Every
+# numeric usage field must additionally satisfy a sane [min, max] bound.
+# Same shared-constant discipline: defined once, used by both usage.sh and
+# transport.sh.
+USAGE_MODEL_MAX_LEN=40
+# jq regex source. IMPORTANT: matched CASE-SENSITIVELY (plain `test($regex)`,
+# NO "i" flag) at both call sites — the suffix is `[a-z0-9]` (lowercase+digit)
+# ON PURPOSE, so an uppercase run (AWS `AKIA...`, mixed-case JWT `eyJ...`)
+# cannot appear even when a secret is prefixed with a vendor token.
+#
+# The suffix is also STRUCTURED like a real version string, not free text: a
+# known vendor prefix, then zero or more `[-._:]`-separated tokens each at most
+# 16 chars. This closes the earlier "prefix-only allowlist" gap where a secret
+# wearing a vendor prefix (`claude-UPPERCASE-REJECTED`, or a long lowercase
+# token) still passed a bare `[a-z0-9._:-]*` suffix. Legitimate model ids this
+# keeps matching: claude-opus-4-8, claude-3-5-sonnet-20241022, claude-fable-5,
+# gpt-5, gpt-4o-2024-08-06, o1, gemini-2.0, glm-5.2. Anything else → "unknown".
+#
+# Residual (accepted, tracked): a caller that FULLY controls the transcript
+# could still pack <=40 chars of lowercase dash-separated text into .model.
+# That requires complete transcript forgery (already in-session code exec),
+# .model is display-only, and the transport backstop is defense-in-depth.
+USAGE_MODEL_REGEX='^(claude|gpt|o[0-9]|gemini|glm|llama|mistral|deepseek|qwen|grok|command|codestral)([._:-][a-z0-9]{1,16})*$'
+
+USAGE_NUMERIC_MIN=0
+USAGE_NUMERIC_MAX=1000000000000

package/scripts/telemetry/telemetry.sh

@@ -294,6 +294,72 @@ add_tool_data_and_emit_delegation() {
   echo "$event"
 }
 
+# add_tool_usage_data — populates .usage on tool.invoke/tool.result events
+# (preToolUse/postToolUse only; see add_event_specific_data's explicit
+# permissionRequest exclusion) with the model/token/cost usage of the turn
+# that produced this specific tool call (#568 slice 1). Same field shape
+# session.usage already emits (model, input_tokens, output_tokens,
+# cache_creation_input_tokens, cache_read_input_tokens, estimated_cost_usd,
+# pricing_version) so console consumers reuse the same parsing path.
+#
+# Fallback tiers (never invent a number):
+#   1. transcript-tail join succeeds (usage_last_turn_usage) -> full usage,
+#      attributable to this exact turn (not the session aggregate).
+#   2. transcript join fails but hook.model is present (and not "unknown")
+#      -> .usage.model only, every token/cost field explicitly null.
+#   3. neither available -> all .usage.* fields null (today's pre-existing,
+#      unchanged no-data state).
+add_tool_usage_data() {
+  local event="$1"
+  local transcript_path hook_model
+  transcript_path=$(echo "$event" | jq -r '.hook.transcript_path // ""')
+  hook_model=$(echo "$event" | jq -r '.hook.model // ""')
+
+  local turn_usage
+  turn_usage=""
+  if [[ -n "$transcript_path" ]]; then
+    turn_usage=$(usage_last_turn_usage "$transcript_path")
+  fi
+
+  if [[ -n "$turn_usage" ]]; then
+    echo "$event" | jq -c --argjson tu "$turn_usage" '. + {
+      usage: {
+        model: $tu.model,
+        input_tokens: $tu.input_tokens,
+        output_tokens: $tu.output_tokens,
+        cache_creation_input_tokens: $tu.cache_creation_input_tokens,
+        cache_read_input_tokens: $tu.cache_read_input_tokens,
+        estimated_cost_usd: $tu.estimated_cost_usd,
+        pricing_version: $tu.pricing_version
+      }
+    }'
+  elif [[ -n "$hook_model" && "$hook_model" != "unknown" ]]; then
+    echo "$event" | jq -c --arg m "$hook_model" '. + {
+      usage: {
+        model: $m,
+        input_tokens: null,
+        output_tokens: null,
+        cache_creation_input_tokens: null,
+        cache_read_input_tokens: null,
+        estimated_cost_usd: null,
+        pricing_version: null
+      }
+    }'
+  else
+    echo "$event" | jq -c '. + {
+      usage: {
+        model: null,
+        input_tokens: null,
+        output_tokens: null,
+        cache_creation_input_tokens: null,
+        cache_read_input_tokens: null,
+        estimated_cost_usd: null,
+        pricing_version: null
+      }
+    }'
+  fi
+}
+
 add_stop_data_and_emit_usage() {
   local event="$1" agent_name="$2"
   local duration_s
@@ -399,7 +465,16 @@ add_event_specific_data() {
     userPromptSubmit|UserPromptSubmit)
       add_user_prompt_data "$event" "$stdin_json"
       ;;
-    preToolUse|PreToolUse|permissionRequest|PermissionRequest|postToolUse|PostToolUse|PostToolUseFailure)
+    preToolUse|PreToolUse|postToolUse|PostToolUse|PostToolUseFailure)
+      event=$(add_tool_data_and_emit_delegation "$event" "$event_type" "$stdin_json")
+      if [[ "$TELEMETRY_USAGE_TRACKING" == "true" ]]; then
+        event=$(add_tool_usage_data "$event")
+      fi
+      echo "$event"
+      ;;
+    permissionRequest|PermissionRequest)
+      # Explicit scope boundary (#568 slice 1): tool.permission_request does
+      # NOT receive .usage enrichment — only preToolUse/postToolUse do.
       add_tool_data_and_emit_delegation "$event" "$event_type" "$stdin_json"
       ;;
     stop|Stop|SessionEnd)

package/src/cli/assignment-provider.ts

@@ -1,5 +1,4 @@
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
@@ -118,25 +117,19 @@ const CLAIM_COMMENT_MARKER_DEFAULT = "<!-- flow-agents:assignment-claim -->";
  */
 function loadActorIdentityHelper(): {
   resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+  resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
   serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
   isUnresolvedActor: (actor: string) => boolean;
   sanitizeSegment: (value: unknown) => string;
-  detectRuntime: (env: NodeJS.ProcessEnv) => string;
-  runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-  ancestorActorSeed: () => string;
-  detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
 } {
   const _req = createRequire(import.meta.url);
   const helperPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../scripts/hooks/lib/actor-identity.js");
   return _req(helperPath) as {
     resolveActor: (env: NodeJS.ProcessEnv) => { actor: string; source: string };
+    resolveActorIdentity: (env: NodeJS.ProcessEnv) => { actor: string; source: string; actorStruct: ActorStruct | null };
     serializeActor: (actor: Partial<ActorStruct> | undefined) => string;
     isUnresolvedActor: (actor: string) => boolean;
     sanitizeSegment: (value: unknown) => string;
-    detectRuntime: (env: NodeJS.ProcessEnv) => string;
-    runtimeSessionId: (env: NodeJS.ProcessEnv) => string;
-    ancestorActorSeed: () => string;
-    detectCiActor: (env: NodeJS.ProcessEnv) => { runtime: string; session_id: string } | null;
   };
 }
 
@@ -209,24 +202,10 @@ function loadActorStruct(args: ParsedArgs): { actor: ActorStruct; actorKey?: str
 
 export function resolveCurrentAssignmentActor(): { actor: ActorStruct; actorKey: string } {
   const helper = loadActorIdentityHelper();
-  const resolved = helper.resolveActor(process.env);
+  const resolved = helper.resolveActorIdentity(process.env);
   if (helper.isUnresolvedActor(resolved.actor)) throw new Error("could not resolve an actor identity (no --actor-json and no resolvable environment actor); pass --actor-json explicitly");
-  // #398: reconstruct the SAME struct resolveActor serialized for a CI actor, mirroring
-  // resolveEnsureSessionActor (workflow-sidecar.ts) via the shared detectCiActor. Without this the
-  // else-branch would write `record.actor = {runtime:"unknown", session_id:<the whole triple>}` for a
-  // CI session — actor_key stays correct (so no false-block), but record.actor is malformed and the
-  // audit-trail / `assignment-provider status` output for CI sessions would be corrupt.
-  const ci = resolved.source.startsWith("ci-runtime") ? helper.detectCiActor(process.env) : null;
-  const runtimeSessionId = resolved.source.startsWith("runtime-session-id") ? helper.runtimeSessionId(process.env) : "";
-  const ancestrySeed = resolved.source === "process-ancestry" ? helper.ancestorActorSeed() : "";
-  const actor: ActorStruct = resolved.source === "explicit-override"
-    ? { runtime: "explicit-override", session_id: resolved.actor, host: os.hostname(), human: null }
-    : ci && ci.session_id
-      ? { runtime: ci.runtime, session_id: ci.session_id, host: os.hostname(), human: null }
-      : runtimeSessionId
-        ? { runtime: helper.detectRuntime(process.env), session_id: runtimeSessionId, host: os.hostname(), human: null }
-        : { runtime: helper.detectRuntime(process.env), session_id: ancestrySeed ? `anc-${ancestrySeed}` : resolved.actor, host: os.hostname(), human: null };
-  return { actor, actorKey: resolved.actor };
+  if (!resolved.actorStruct) throw new Error("actor identity resolved without a canonical actor struct");
+  return { actor: { ...resolved.actorStruct, human: resolved.actorStruct.human ?? null }, actorKey: resolved.actor };
 }
 
 export function assignmentFilePath(artifactRoot: string, subjectId: string): string {