@kontourai/flow-agents 3.9.0 → 3.10.0

package/context/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/docs/coordination-guide.md

@@ -67,16 +67,18 @@ this section before the rest.
 
 ### The resolution chain
 
-`resolveActor(env)` (in `scripts/hooks/lib/actor-identity.js`, mirrored in `src/cli`) returns
+`resolveActor(env)` (in the canonical `scripts/hooks/lib/actor-identity.js`, loaded by TypeScript consumers rather than mirrored) returns
 `{ actor, source }` by trying four sources in strict priority order:
 
 1. **`explicit-override`** — `FLOW_AGENTS_ACTOR` is set. The actor is the **bare token** you provided,
    verbatim. Source string: `"explicit-override"`.
-2. **`runtime-session-id:<runtime>`** — the host runtime exposes a native session id (e.g. Claude
-   Code). The actor is a **serialized triple** `runtime:session:host`. Source string:
+2. **`runtime-session-id:<runtime>`** — the host runtime exposes a native session id. For Codex,
+   `CODEX_THREAD_ID` is preferred over the legacy-compatible `CODEX_SESSION_ID`. The raw thread id
+   is never persisted: it becomes a domain-separated 96-bit `thread-<digest>` token. The actor is a **serialized triple** `runtime:session:host`. Source string:
    `"runtime-session-id:<runtime>"`.
-3. **`process-ancestry`** — no session id; identity is derived by walking the process tree. Also a
-   serialized triple. Source string: `"process-ancestry"`.
+3. **`process-ancestry`** — no session id; identity is derived from the parent process and start
+   time. It is serialized explicitly as `process-ancestry:anc-<digest>:<host>`, never as an
+   `unknown` runtime. Source string: `"process-ancestry"`; this remains unstable/advisory.
 4. **`unresolved`** — nothing worked. Source string: `"unresolved"`.
 
 The `"local"` literal default from the old design is **retired as an error, not a fallback** — a
@@ -116,6 +118,10 @@ A record written by a current session has `actor_key` and compares canonically;
 it falls back to `serializeActor`, reproducing pre-#291 behavior exactly. This one field is why the
 override/derived divergence no longer bites.
 
+Historical `unknown:anc-*` values remain opaque, readable actor keys and are not rewritten or
+aliased. Because ancestry is intentionally unstable, a process crossing this upgrade boundary may
+need to release/reclaim rather than treating the old and new display forms as the same identity.
+
 ### Stable vs. unstable identity (this powers the publish gate)
 
 The `source` matters beyond attribution. An identity is **stable** if it came from
@@ -231,6 +237,16 @@ state rather than guesswork. A crash skips this — and that's fine: the livenes
 to `stale`, the assignment becomes `reclaimable`, and takeover (§10) handles it. Clean release just
 makes the common case instant instead of TTL-delayed.
 
+**Ownership scoping (#440):** the Stop hook's evidence scanning, its non-terminal release (above), the
+tool-activity liveness heartbeat, and the SessionStart/UserPromptSubmit re-ground banner all resolve
+**only** from the stopping/heartbeating/steered actor's own per-actor `current/<actor>.json` pointer
+when that actor is resolved — never from the shared legacy `current.json` or a repo-wide newest-mtime
+scan, which would otherwise let a session co-located with another actor's work inherit that actor's gate
+debt or steer onto its slug. Accepted gap: a resolved actor with no per-actor pointer yet (pre any
+`workflow-sidecar` command in this session) is simply ungated/unbannered until its next sidecar command
+establishes one — never gated on another actor's unrelated work. An unresolved actor keeps the pre-#440
+legacy-fallback behavior unchanged (compat + anti-gaming: identity cannot be unset to escape the gate).
+
 ## 8. Guard point 3 — the verify-hold publish gate (the one hard fence)
 
 This is the **only** place coordination *blocks*, and it earned three fix iterations, so its design is

package/docs/fixture-ownership.md

@@ -17,6 +17,7 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |
+| `evals/fixtures/codex-legacy-agents` | exact historical Flow Agents-generated Codex AGENTS.md migration fixtures (#563) | `evals/integration/test_install_merge.sh` | Keep while the Codex home installer recognizes audited historical payload hashes, refuses before mutation, and provides explicit operator remediation without fuzzy ownership matching. |
 | `evals/fixtures/economics` | per-run kit-economics record fixtures (#349): a transcript with .message.usage blocks, state.json/acceptance.json/critique.json join sources, a session.usage event, and the golden expected kontour.console.economics record | `evals/integration/test_economics_record.sh` | Keep while the `kontour.console.economics` v0.1 record contract (docs/specs/economics-record-contract.md) is enforced; the golden proves cost-from-transcript, defects-from-critique, verdict-from-state, and the R7 co-required guard. |
 | `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/integration/test_activate_npx_context.sh`, `evals/integration/test_flow_kit_install_git.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
 | `evals/fixtures/kit-conformance-levels` | K-level conformance and consumer-target derivation fixtures | `evals/integration/test_kit_conformance_levels.sh` | Keep while K-level derivation, degradation invariant, and consumer-target badge rules are tested. |
@@ -26,7 +27,7 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
 | `evals/fixtures/reconcile-preflight` | #356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim) | `evals/integration/test_reconcile_preflight.sh` | Keep while the local `reconcile-preflight` subcommand (#356) is proven against the two shapes trust-reconcile-exploits does not already fixture (un-superseded disputed critique, standalone disputed session-local claim); the other four shapes reuse trust-reconcile-exploits/trust-reconcile-mixed-bundle directly rather than forking near-duplicates. |
 | `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
-| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage) is proven against a hermetic multi-model transcript rather than relying on live runtime data. |
+| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh`, `evals/integration/test_telemetry_tool_usage.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage / usage_last_turn_usage) is proven against hermetic multi-model and oversized-prefix transcripts rather than relying on live runtime data. |
 | `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies) | `evals/integration/test_trust_reconcile_negatives.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
 | `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case | `evals/integration/test_trust_reconcile_mixed_bundle.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
 | `evals/fixtures/trust-reconcile-ws3` | WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while backward compatibility with pre-classification (all-test_output) bundles is asserted; proves an old-style bundle still FAILS the same way (no silent pass). |

package/docs/public-workflow-cli.md

@@ -167,6 +167,50 @@ state rollback or deletion is rejected when its append-only event history proves
 started. These local coordination records detect accidental or in-process rollback; they are not a
 cryptographic boundary against a process that can rewrite the entire artifact directory.
 
+Immediately before spawning an adapter turn, the driver writes a transient, schema-versioned
+`active-turn.json` beside its mission state and passes a raw 32-byte turn secret plus the path-safe,
+signed run id in `FLOW_AGENTS_CONTINUATION_TURN_SECRET` and
+`FLOW_AGENTS_CONTINUATION_RUN_ID` to that child. Only the secret's SHA-256 is persisted in the signed
+record. The driver's schema-1-compatible mission state separately stores the ephemeral public-key
+digest before the adapter starts, so replacing and correctly re-signing the entire active-turn
+record with another key does not replace the signer anchor. The driver clears that digest with the
+active-turn step on every completion, error, cleanup, terminal, waiting, and budget path. It replaces
+every inherited continuation capability variable but preserves ordinary
+`FLOW_AGENTS_ACTOR`. The shared actor
+resolver remains ordinary: it never accepts continuation data as an identity override. When an
+assignment-gated public workflow command finds that ordinary resolution does not match, it may use
+only a live signed active-turn record bound to the exact session, turn secret, run id, assignment file and
+actor struct, mission, adapter identity, expiry, and driver lock; it returns the signed assignment
+identity only for that active-turn evidence gate. Pause, resume, release, cancel, and archive remain
+control-plane operations: they require ordinary actor identity or their existing explicit external
+authority and never accept this turn capability. The private key remains only in the driver process.
+The Stop hook resolves the signed run id under the canonical artifact root and fully validates that
+exact session before consulting ordinary current pointers. Once the base signed turn remains valid,
+that exact session stays selected even if canonical Flow has become paused, blocked, completed, or
+another canonical disposition; Stop never falls back to a conflicting actor or global pointer. It
+securely validates canonical state against the run's definition and treats only canonical `active`
+as authority to make the ordinary unfinished
+canonical-gate warning advisory so the adapter can return control to the driver. It never advances
+a Flow gate, releases assignment or liveness for a continuation-owned nonterminal run, or relaxes evidence, integrity, false-completion,
+malformed-state, or configuration blocks. The record is removed when the child completes, errors,
+or times out; parent identity changes leave it to expire instead of unlinking through a replacement.
+
+This is cooperative same-user protection, not cryptographic filesystem isolation from a hostile
+same-UID process. A same-UID process that can rewrite both mission state and authority records or
+control the driver process remains outside this boundary. Within the cooperative boundary, the
+mission digest anchors the driver's ephemeral signer, while descriptor reads, final-path inode rechecks, and realpath/device/inode parent
+rechecks detect practical replacement races. Active-turn and lock records are capped at 16 KiB;
+canonical assignment and continuation mission records are capped at a conservative 1 MiB so valid
+provider metadata is not rejected. PID liveness is best-effort only: PID reuse and same-UID process control remain outside this
+local coordination boundary.
+
+The event stream records `turn_completed`, `gate_not_advanced`, `turn_failed`, and best-effort
+`authority_cleanup_failed`. Cleanup failures are audited but do not replace the adapter or canonical
+outcome. Failed turns carry
+`failure_kind` of `timeout` or `adapter_error`; a completed adapter turn whose canonical run remains
+active at the same current step records `gate_not_advanced`. These events describe driver execution only and do not
+change canonical Flow state.
+
 ## Compatibility Doctor
 
 Run doctor through the exact isolated package helper defined above:

package/docs/spec/runtime-hook-surface.md

@@ -27,13 +27,15 @@ Every Flow Agents event has a canonical name that is runtime-neutral. Adapters m
 | --- | --- | --- | --- |
 | `agentSpawn` | A new agent session starts. Maps from `SessionStart` on Claude Code and Codex. | `hook_event_name`, `cwd` | `session_id`, `agent_id`, `model`, `runtime` |
 | `userPromptSubmit` | The user submits a new turn or message. Maps from `UserPromptSubmit`. | `hook_event_name` | `turn.prompt_text` (redacted by default), `cwd` |
-| `preToolUse` | Immediately before a tool call is executed. Maps from `PreToolUse`. | `hook_event_name`, `tool_name`, `tool_input` | `tool_id`, `cwd` |
+| `preToolUse` | Immediately before a tool call is executed. Maps from `PreToolUse`. | `hook_event_name`, `tool_name`, `tool_input` | `tool_id`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
 | `permissionRequest` | The runtime is asking for permission to run a tool or action. Maps from `PermissionRequest`. | `hook_event_name`, `tool_name` | `tool_input`, `cwd` |
-| `postToolUse` | After a tool call completes (success or failure). Maps from `PostToolUse` and `PostToolUseFailure`. | `hook_event_name`, `tool_name`, `tool_response` | `tool_input`, `tool_output`, `error`, `cwd` |
+| `postToolUse` | After a tool call completes (success or failure). Maps from `PostToolUse` and `PostToolUseFailure`. | `hook_event_name`, `tool_name`, `tool_response` | `tool_input`, `tool_output`, `error`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
 | `stop` | The agent is about to stop and return control to the user. Maps from `Stop` and `SessionEnd`. | `hook_event_name` | `stop_reason`, `cwd` |
 | `subagentStart` | A subagent or specialist delegate is spawning. Maps from `SubagentStart` (Claude Code). | `hook_event_name` | `agent_name`, `agent_type` |
 | `subagentStop` | A subagent or specialist delegate has stopped. Maps from `SubagentStop` (Claude Code). | `hook_event_name` | `agent_name`, `outcome` |
 
+**`usage.*` on `preToolUse`/`postToolUse` (#568 slice 1).** These two events carry an optional `.usage` object — `model`, `input_tokens`, `output_tokens`, `cache_creation_input_tokens`, `cache_read_input_tokens`, `estimated_cost_usd`, `pricing_version` — sourced from the runtime transcript's LAST assistant turn (the turn that produced this specific tool call), joined via a bounded tail-read of `hook.transcript_path`. This is **per-turn, not a per-tool-call cost fraction**: multiple tool calls inside the same assistant turn (parallel tool_use blocks) report the *same* whole-turn usage figures — do not sum `estimated_cost_usd` across `tool.invoke`/`tool.result` rows within one turn, or cost will be double-counted; `session.usage`'s cumulative totals remain the authoritative aggregate. When the transcript join is unavailable but the runtime's `.model` hook field is present, only `usage.model` is populated and every token/cost field is explicitly `null` (never a guessed number); `.model` itself is best-effort on these two events (see §8.2), not a contractually guaranteed field. `tool.permission_request` (`permissionRequest`) is explicitly excluded from this enrichment.
+
 ### Redaction Defaults
 
 Telemetry channels redact sensitive payload fields before emission. Adapters must honor these defaults and must not log raw hook payloads without applying channel redaction.
@@ -518,11 +520,13 @@ All payloads are a single JSON object on stdin. Required and optional fields:
 
 | Canonical event | Required fields | Optional fields |
 |----------------|-----------------|-----------------|
-| `preToolUse` | `hook_event_name` | `tool_name`, `tool_input.path`, `tool_input.file_path`, `cwd` |
-| `postToolUse` | `hook_event_name` | `tool_name`, `tool_input.path`, `tool_input.file_path`, `tool_response`, `cwd` |
+| `preToolUse` | `hook_event_name` | `tool_name`, `tool_input.path`, `tool_input.file_path`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
+| `postToolUse` | `hook_event_name` | `tool_name`, `tool_input.path`, `tool_input.file_path`, `tool_response`, `cwd`, `usage.model`, `usage.input_tokens`, `usage.output_tokens`, `usage.cache_creation_input_tokens`, `usage.cache_read_input_tokens`, `usage.estimated_cost_usd`, `usage.pricing_version` |
 | `userPromptSubmit` | `hook_event_name` | `tool_input` (for subagent calls), `cwd` |
 | `stop` | `hook_event_name` | `cwd`, `stop_reason` |
 
+`usage.*` on `preToolUse`/`postToolUse` above is emitted output, not required input — it is populated by the telemetry adapter from the runtime transcript's last assistant turn (or degrades to `usage.model`-only / fully-null per the documented fallback tiers in §1), not read from the hook's stdin payload. It is **per-turn**, not a per-tool-call cost fraction: consumers must not sum `estimated_cost_usd` across tool events within the same assistant turn (see §1). The runtime-native `.model` field these events derive part of this from is best-effort, not contractually guaranteed by any host today.
+
 `hook_event_name` is the **host-native** event name (e.g., `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) or may be omitted — policy scripts read the canonical fields (`tool_input.path`, `cwd`) directly and do not require the event name field for their decisions.
 
 ### 8.3 Decision schema (stdout / exit code)

package/evals/acceptance/prove-capture-teeth-declared.sh

@@ -22,6 +22,19 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# #440 FIXTURE-GAP: this suite's fixtures were written before #440's per-actor ownership scoping
+# and never establish a per-actor current pointer for the invoking actor -- under a RESOLVED
+# ambient actor (ancestry-derived locally, GITHUB_RUN_ID-derived CI-runtime in CI), stop-goal-fit.js's
+# analyze() (and evidence-capture.js's resolveArtifactDir) now scope to that actor's own
+# (nonexistent) pointer and never reach the fixture-under-test at all. This suite is about
+# anti-gaming/capture-teeth mechanics, not #440's ownership scoping, so forcing the documented
+# test-only unresolved-actor escape hatch restores EXACTLY this suite's pre-#440 behavior (D3
+# compat: an unresolved actor keeps the unchanged legacy-fallback/global-scan discovery every
+# assertion below was written against). `env`-prefixed subprocess invocations below inherit this
+# exported pair (env without -i does not clear the parent environment).
+export FLOW_AGENTS_ACTOR_TEST_FORCE_UNRESOLVED=1
+export NODE_ENV=test
+
 GATE="$ROOT/scripts/hooks/stop-goal-fit.js"
 
 export FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS=100000

package/evals/acceptance/prove-capture-teeth.sh

@@ -12,6 +12,19 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+# #440 FIXTURE-GAP: this suite's fixtures were written before #440's per-actor ownership scoping
+# and never establish a per-actor current pointer for the invoking actor -- under a RESOLVED
+# ambient actor (ancestry-derived locally, GITHUB_RUN_ID-derived CI-runtime in CI), stop-goal-fit.js's
+# analyze() (and evidence-capture.js's resolveArtifactDir) now scope to that actor's own
+# (nonexistent) pointer and never reach the fixture-under-test at all. This suite is about
+# anti-gaming/capture-teeth mechanics, not #440's ownership scoping, so forcing the documented
+# test-only unresolved-actor escape hatch restores EXACTLY this suite's pre-#440 behavior (D3
+# compat: an unresolved actor keeps the unchanged legacy-fallback/global-scan discovery every
+# assertion below was written against). `env`-prefixed subprocess invocations below inherit this
+# exported pair (env without -i does not clear the parent environment).
+export FLOW_AGENTS_ACTOR_TEST_FORCE_UNRESOLVED=1
+export NODE_ENV=test
+
 pass=0; fail=0
 _p(){ echo "  ✓ $1"; pass=$((pass+1)); }
 _f(){ echo "  ✗ $1"; fail=$((fail+1)); }

package/evals/ci/run-baseline.sh

@@ -59,6 +59,7 @@ CHECKS=(
   "Telemetry doctor integration|bash evals/integration/test_telemetry_doctor.sh"
   "Usage and cost integration|bash evals/integration/test_usage_cost.sh"
   "Telemetry usage pipeline integration|bash evals/integration/test_telemetry_usage_pipeline.sh"
+  "Telemetry tool usage integration|bash evals/integration/test_telemetry_tool_usage.sh"
   "Economics record integration|bash evals/integration/test_economics_record.sh"
   "Learning review proposals integration|bash evals/integration/test_learning_review_proposals.sh"
   "Utterance check integration|bash evals/integration/test_utterance_check.sh"
@@ -152,6 +153,7 @@ LANE_RUNTIME_AND_KIT=(
   "Telemetry doctor integration"
   "Usage and cost integration"
   "Telemetry usage pipeline integration"
+  "Telemetry tool usage integration"
   "Economics record integration"
   "Learning review proposals integration"
   "Utterance check integration"

package/evals/fixtures/codex-legacy-agents/5273878130bdafc8a024a650bb5b66c9b003f1f859b5dc6e5b588cbf4ab23228.md

@@ -0,0 +1,25 @@
+# Universal Agent Bundle (Codex)
+
+This bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.
+
+## Shared Conventions
+
+- `skills/`, `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/` were copied from the canonical source.
+- Cross-session task artifacts should live under `.kontourai/flow-agents`.
+- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.
+
+## Exported Agents
+
+- `tool-code-reviewer` — Delegate to me for code quality review. Analyzes readability, maintainability, patterns, DRY compliance, and produces structured review with severity levels. Separate from verification (build/test/lint).
+- `tool-dependencies-updater` — Delegate to me for updating your project dependencies - checks latest versions, identifies outdated packages, and finds security advisories across npm, PyPI, Cargo, Maven/Gradle, Go, NuGet, Ruby, PHP, Swift, Dart, Docker, Helm, Terraform, and GitHub Actions
+- `tool-explore-config` — Delegate to me for project configuration inspection - finds and summarizes configuration files and environment variables within a project
+- `tool-explore-deps` — Delegate to me for Dependency analysis - parses package manifests to identify tech stack and dependencies
+- `tool-explore-entry` — Delegate to me to find the Entry point of a project - locates main files, CLI commands, API routes, and exports
+- `tool-explore-patterns` — Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions
+- `tool-explore-structure` — Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase
+- `tool-explore-tests` — Delegate to me to find and understand testing strategies - locates test files and understands testing strategy
+- `tool-planner` — Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .kontourai/flow-agents. No production file modifications.
+- `tool-playwright` — Delegate to me for browser automation, testing, and debugging - loading real pages, testing navigation, checking accessibility via structured snapshots, evaluating scripts, and visual verification. Anything that would otherwise require a browser. Do NOT use for general web search or fetching content
+- `tool-security-reviewer` — Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools.
+- `tool-verifier` — Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .kontourai/flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No production file modifications.
+- `tool-worker` — Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell tools. WARNING: May spawn a `git worktree`

package/evals/fixtures/telemetry/usage-transcript-adversarial.jsonl

@@ -0,0 +1,2 @@
+{"type":"user","message":{"role":"user","content":"benign filler line so the adversarial assistant line is not the only content"}}
+{"type":"assistant","message":{"model":"SYSTEM PROMPT LEAK: the user's SSN is 000-00-0000 and API key sk-FAKE-adversarial-fixture","usage":{"input_tokens":"the user's private prompt said: attack the server at 203.0.113.7 with admin/hunter2","output_tokens":"also-not-a-number","cache_creation_input_tokens":{"nested":"object"},"cache_read_input_tokens":[1,2,3]}}}

package/evals/fixtures/telemetry/usage-transcript-malformed-sandwich.jsonl

@@ -0,0 +1,3 @@
+{"type":"assistant","message":{"model":"bad-before" this line is not valid JSON at all
+{"type": "assistant", "message": {"model": "claude-malformed-sandwich-safe", "usage": {"input_tokens": 10, "output_tokens": 20, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}}}
+{this is not json either, noise after the valid line

package/evals/fixtures/telemetry/usage-transcript-negative-tokens.jsonl

@@ -0,0 +1 @@
+{"type": "assistant", "message": {"model": "claude-opus-4-8", "usage": {"input_tokens": -500, "output_tokens": 20, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}}}