pi-dev-team 0.2.0

package/scripts/lib/session_log/records.py

@@ -0,0 +1,218 @@
+"""JSONL record iteration and the ``usage``-block read contract (issue
+#2042, epic #2040).
+
+Usage-block contract: today nine modules across this repo read a
+transcript's ``usage`` block with four different idioms —
+
+  1. ``usage.get(field, 0) or 0``          -> 0 on missing key AND on null
+  2. ``usage.get(field) or 0``              -> 0 on missing key AND on null
+  3. ``usage.get(field, 0)``                -> 0 on missing key, but a
+                                                PRESENT-and-null value
+                                                survives as `None`
+  4. ``usage[field]``                       -> raises `KeyError` on a
+                                                missing key
+
+``usage_field`` below is idiom 1/2 (they are equivalent) — the idiom already
+used by BOTH extractors' own ``_accumulate_token_signals``/``_cost`` before
+this package existed, so choosing it keeps golden output byte-identical
+(#2042 acceptance criterion).
+
+Why this one, not idiom 3 or 4: a real Claude Code transcript legitimately
+omits a usage field two different ways. A `thinking`-only assistant message
+carries no `usage` key at all (the corpus's record #2 in
+`tests/fixtures/session_log/projects/.../99999999….jsonl`). A model turn
+that doesn't support prompt caching has been observed to emit the field
+explicitly as `usage: {"cache_creation_input_tokens": null, ...}` rather
+than omitting the key (the corpus's record #3). Both cases mean the same
+thing — "this field was not populated, count it as zero" — never a
+legitimate non-zero value inferred from its absence. Idiom 3 would leave a
+`None` sitting in an accumulator the moment a null-but-present field is hit,
+raising a `TypeError` the next time arithmetic touches it (`+=`, `/ 1e6`).
+Idiom 4 would abort the WHOLE extraction on the first transcript missing any
+field — observed on real transcripts, not hypothetical. Idiom 1/2 is the
+only one of the four that treats "missing" and "null" identically, which is
+the behavior a `usage` block actually needs.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+#: The four fields every extractor's token accounting reads from a usage
+#: block, in the order both extractors already declared them.
+USAGE_FIELDS = (
+    "input_tokens",
+    "output_tokens",
+    "cache_creation_input_tokens",
+    "cache_read_input_tokens",
+)
+
+
+def iter_file_records(path: Path):
+    """Yield every decodable JSON record in one transcript file, in order.
+
+    Streams line by line rather than `read_text().splitlines()`: transcripts
+    run to tens of MB and a recursive scan can visit thousands of them, where
+    slurping costs ~3x the file's size in peak RSS before yielding anything.
+    `ValueError` is caught alongside `OSError` because `UnicodeDecodeError`
+    is a `ValueError` — a transcript truncated mid-character by a crashed
+    session must not abort the whole run. `extract_session_report.py`'s
+    pre-#2042 copy of this function caught only `OSError`; `session_extract.py`'s
+    copy already had the wider catch (#1994 review) — this module keeps the
+    wider, safer one for both callers."""
+    try:
+        with path.open(encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    yield json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+    except (OSError, ValueError):
+        return
+
+
+def usage_of(record: dict) -> dict | None:
+    """Resolve one record's usage block: `message.usage` if it's a dict,
+    else the record's own top-level `usage` if THAT's a dict, else `None`.
+    Both extractors' `extract()` loops used this exact resolution order
+    already — moved verbatim, not changed."""
+    msg = record.get("message") if isinstance(record.get("message"), dict) else {}
+    if isinstance(msg.get("usage"), dict):
+        return msg["usage"]
+    if isinstance(record.get("usage"), dict):
+        return record["usage"]
+    return None
+
+
+def usage_field(usage: dict, field: str) -> int | float:
+    """The one canonical reader for a single usage field. See module
+    docstring for the chosen null-handling contract."""
+    return usage.get(field, 0) or 0
+
+
+def usage_fields(usage: dict) -> dict[str, int | float]:
+    """Every `USAGE_FIELDS` entry read through `usage_field`, in order."""
+    return {f: usage_field(usage, f) for f in USAGE_FIELDS}
+
+
+def slim_by_name(mapping: dict) -> dict:
+    """Sort a name-keyed dict of Counters into a deterministic, digest-ready
+    shape: outer keys sorted, and each inner Counter's keys sorted too.
+    Shared by `session_extract.py`'s `by_model`/`by_skill` and
+    `extract_session_report.py`'s `by_model` — both built this exact shape
+    independently (the former as a dedicated `_slim` helper, the latter
+    inline)."""
+    return {k: dict(sorted(v.items())) for k, v in sorted(mapping.items())}
+
+
+# --- issue #2050: sidechain/attribution primitives, made public -----------
+#
+# `hooks/lib/cost_meter.py`, the former context ceiling guard, and
+# `scripts/measure_full_file_duplication.py` each independently read the
+# harness's `isSidechain`/`attributionAgent` fields and (`cost_meter.py`/
+# `measure_full_file_duplication.py`) the Task/Agent-dispatch join. Folded
+# here so `skills/code-review/scripts/repo_invariants.py`'s
+# `check_transcript_parsing_confined_to_session_log` (#2048) has one real
+# home to point at instead of three independent copies.
+
+#: Tool names the harness uses for subagent dispatch (both spellings appear
+#: in real transcripts depending on harness version).
+TASK_TOOL_NAMES = ("Task", "Agent")
+
+
+def is_sidechain(record: dict) -> bool:
+    """True for a subagent (sidechain) transcript record — the native
+    top-level `isSidechain` flag, true on subagent/sidechain turns under
+    the older inline-record harness layout."""
+    return bool(record.get("isSidechain"))
+
+
+def attribution_agent_of(record: dict) -> str | None:
+    """The record's own `attributionAgent` value when it's a string
+    (possibly empty), else `None`. Deliberately does not filter on
+    truthiness here — callers that require a non-empty value check it
+    themselves (`agent_type_for` below does; a caller collecting the first
+    attribution seen across a file, so it can prefer a later non-empty one,
+    does not)."""
+    value = record.get("attributionAgent")
+    return value if isinstance(value, str) else None
+
+
+def join_dispatch_agent_ids(
+    record: dict, dispatch_types: dict[str, str], agent_types: dict[str, str]
+) -> None:
+    """Fold one record's subagent-dispatch metadata into the two join maps,
+    in place.
+
+    Two harness-recorded halves of the join (#1094):
+      * an assistant `tool_use` block named Task/Agent carries
+        `input.subagent_type` — keyed here by the block's tool-use id;
+      * the paired `tool_result` user record carries top-level
+        `toolUseResult.agentId` — completing agentId -> subagent_type.
+
+    Only the identifiers are read; prompts/descriptions are never touched.
+    Previously duplicated independently by `hooks/lib/cost_meter.py`'s
+    `_harvest_agent_dispatch` and `scripts/measure_full_file_duplication.py`'s
+    `_join_dispatch_agent_ids` — the latter's own docstring already conceded
+    the duplication "since that algorithm's own module keeps it private"
+    (#2050 makes it public here instead, so both consumers share one
+    implementation)."""
+    message = record.get("message")
+    content = message.get("content") if isinstance(message, dict) else None
+    if not isinstance(content, list):
+        return
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        block_type = block.get("type")
+        if block_type == "tool_use" and block.get("name") in TASK_TOOL_NAMES:
+            block_id = block.get("id")
+            block_input = block.get("input")
+            subagent_type = (
+                block_input.get("subagent_type")
+                if isinstance(block_input, dict)
+                else None
+            )
+            if (
+                isinstance(block_id, str)
+                and isinstance(subagent_type, str)
+                and subagent_type
+            ):
+                dispatch_types[block_id] = subagent_type
+        elif block_type == "tool_result":
+            tool_use_id = block.get("tool_use_id")
+            tool_use_result = record.get("toolUseResult")
+            agent_id = (
+                tool_use_result.get("agentId")
+                if isinstance(tool_use_result, dict)
+                else None
+            )
+            if (
+                isinstance(tool_use_id, str)
+                and isinstance(agent_id, str)
+                and tool_use_id in dispatch_types
+            ):
+                agent_types[agent_id] = dispatch_types[tool_use_id]
+
+
+def agent_type_for(record: dict, agent_types: dict[str, str]) -> str:
+    """Agent-type bucket for one usage-bearing record (#1094).
+
+    `main` for main-loop turns. For sidechain turns: the native
+    `attributionAgent` field (primary), else the agentId -> subagent_type
+    join built from Task/Agent dispatches via `join_dispatch_agent_ids`
+    (fallback), else the honest `unattributed` bucket — never a guess.
+    """
+    if not is_sidechain(record):
+        return "main"
+    attribution_agent = attribution_agent_of(record)
+    if attribution_agent:
+        return attribution_agent
+    agent_id = record.get("agentId")
+    if isinstance(agent_id, str) and agent_id in agent_types:
+        return agent_types[agent_id]
+    return "unattributed"

package/scripts/lib/session_log/redact.py

@@ -0,0 +1,76 @@
+"""The privacy boundary as a function, not a convention (issue #2045, epic
+#2040).
+
+Both extractors' own docstrings promise "metrics only — no prompt text,
+code, file contents, or full command strings", and
+``knowledge/telemetry-schema.md`` states the same contract. Before this
+module existed, that promise was enforced only by every call site
+individually remembering to run a name/path through
+``classify.safe_name``/``classify.basename`` — a convention restated at (at
+last count) seventeen call sites across ``scripts/session_extract.py``,
+``plugins/dev-team/scripts/extract_session_report.py``, and
+``session_log/signals.py``. That is exactly the shape that produced this
+epic (#1990/#1991/#1994: the same defect landing independently in both
+forked extractors because nothing forced a shared choke point). This module
+is that choke point: one function, ``redact()``, that every field value
+either extractor writes to its output passes through.
+
+``redact()`` does not duplicate ``classify.safe_name``/``classify.basename``
+— it composes them. Those two functions, and their Windows-path/allowlist
+rationale, are unchanged and still individually tested; this module adds
+the privacy-labeled entry point + the two-shape contract below, so a reader
+(and a future call site) reaches for ``redact()`` by name rather than
+re-deriving "should this be safe_name'd, basename'd, or both" from
+scratch.
+
+Real defect found while wiring this up (fixed in the same commit, not
+paranoia): ``extract_session_report.py``'s ``_project_label`` used
+``os.path.basename(os.path.normpath(cwd))`` instead of the shared,
+Windows-path-aware ``classify.basename`` — on a POSIX host (where this
+script runs), ``os.path.basename`` splits on ``/`` only, so a Windows-
+authored transcript's backslash-separated ``cwd`` came back whole. It
+did not leak the raw path (``classify.safe_name``'s allowlist has no
+backslash in it, so the value collapsed to ``"other"``), but every such
+project's label lost its real name — this is the exact defect class the
+epic's own "why this is not paranoia" note warns about (``_basename``'s
+Windows-path handling is a privacy fix a hand-port already dropped once),
+found a third time by routing this call site through the shared primitive
+instead of a bespoke one.
+
+Stdlib only. See ADR 0014 / ADR 0015.
+"""
+
+from __future__ import annotations
+
+from . import classify
+
+
+def redact(value: str, *, from_path: bool = False) -> str:
+    """The one function every name/label-shaped field value passes through
+    before either extractor writes it to its emitted output.
+
+    - ``from_path=True``: the caller KNOWS ``value`` is a filesystem path (a
+      tool's ``file_path`` input, a transcript's ``cwd``) — strip to the
+      last path component first (``classify.basename``), then apply the
+      strict character allowlist (``classify.safe_name``).
+    - ``from_path=False`` (default): apply the strict character allowlist
+      directly, with NO path-stripping.
+
+    Deliberately not "always basename first, regardless of what the value
+    is" — a full shell command string like
+    ``rm -rf /tmp/SENTINEL_CMD_do_not_leak`` would basename down to
+    ``SENTINEL_CMD_do_not_leak`` (letters/underscores only, no slash), which
+    WOULD then pass the allowlist: stripping everything before the last
+    ``/`` can turn an unsafe string into one that only *looks* safe. The
+    two-shape signature keeps that failure mode impossible — a value is
+    only ever basenamed when the caller has affirmatively marked it as a
+    path.
+
+    A value that fails the allowlist collapses to ``"other"`` — never
+    partial content, never raised. See ``classify.safe_name``'s own
+    docstring for the allowlist rationale and ``classify.basename``'s for
+    the Windows-path history (#1991/#1994) this composes on top of,
+    unchanged."""
+    if from_path:
+        value = classify.basename(value)
+    return classify.safe_name(value)

package/scripts/lib/session_log/signals.py

@@ -0,0 +1,373 @@
+"""Per-record signal accumulation shared by both session-log extractors
+(issue #2044, epic #2040) — the six drifted-furthest accumulator functions
+plus one more that does the same job under a different name (`detect_
+correction_turn`; the issue's own table names 7 functions while its prose
+says "six", the issue is transparent about this discrepancy — the seventh is
+the accuracy signal's "was this a correction turn" classifier, drifted right
+alongside the other six).
+
+Unlike session_log.discovery/records/classify (slices #2042/#2043), THIS
+slice is not behavior-preserving on purpose — see the module-level and
+per-function notes below for what changed, in which direction, for which
+extractor, and the historical-comparability consequence. A distilled
+enumeration also lives in this slice's commit body; this docstring is the
+canonical, in-code record of the same decisions.
+
+The four signal classes `/session-review`'s contract defines (docstring of
+scripts/session_extract.py, mirrored in
+plugins/dev-team/knowledge/telemetry-schema.md's `session-digest.jsonl`
+section):
+
+  token      per-session / per-skill / per-subagent / per-model token +
+             cost, and the cache-hit ratio.
+  rework     failed edits, repeated file edits, retried bash, repeated
+             verify-loop runs, permission denials, compaction events.
+  accuracy   tool_result is_error counts by tool, failed->retried ratio,
+             and user-correction turns.
+  utilization which skills/agents were invoked and how often, and which
+             registered skills/agents were never observed.
+
+## Per-function reconciliation
+
+- **accumulate_token_signals** (0.10 similarity). The CORE accumulation —
+  sum the 4 usage fields into `tokens_total` and `by_model[model]` — is
+  identical in effect between the two copies; kept as the shared function,
+  matching `extract_session_report.py`'s existing shape exactly (no cost, no
+  skill). Cost computation and per-skill attribution are session_extract.py-
+  only EXTENSIONS layered on top by that script's own wrapper (pricing/cost
+  stays forked per ADR 0036) — not duplicated here.
+
+- **The per-agent CONTEXT_TOKEN bucket (`new_agent_bucket`/
+  `merge_agent_buckets`/`finalize_agent_buckets`)** — not one of the 7 named
+  functions, but the mechanism #2029 added to `extract_session_report.py`
+  ONLY, giving its `by_agent_type` entries real per-agent `context_tokens`/
+  `context_per_dispatch` figures. `scripts/session_extract.py` had no
+  equivalent — its `by_agent_type` was a bare message-count `Counter`. This
+  slice ports the bucket machinery here and switches `session_extract.py`'s
+  `by_agent_type` onto it too, so **the maintainer profile gains
+  `context_tokens`/`context_per_dispatch`** — the deliberate, expected
+  output change issue #2044 calls the "clearest example of why the fork
+  costs something."
+
+- **accumulate_skill_agent_signals** (0.19 similarity). session_extract.py's
+  copy is a strict superset: it also tracks `active` (the #711 sticky
+  skill/agent pointer the correction-turn signal attributes against) and
+  reads a legacy `attributionSkill` fallback via a `skill` parameter.
+  `extract_session_report.py` has neither concern (no by_skill/by_agent
+  correction breakdown in its report shape). The superset function is kept
+  as canonical; `extract_session_report.py` calls it with `skill=None` and a
+  throwaway `active` dict it never reads back — with `skill=None` the
+  legacy-fallback branch never fires, so its own `skills_invoked`/
+  `agent_dispatches` accumulation is unchanged (verified by golden diff
+  absence on that specific field).
+
+- **track_tool_call** (0.11 similarity) and **classify_tool_result** (0.50).
+  Real difference: session_extract.py guards a `tool_use`/`tool_result`
+  block's `id`/`tool_use_id` with `isinstance(..., str)` before using it as
+  a dict key; extract_session_report.py's pre-#2044 copies did a bare
+  `.get(bid, ...)`/dict assignment, which works for any hashable `bid` but
+  raises `TypeError` for an unhashable one (a list or dict — a malformed or
+  adversarial transcript field). The safer, guarded form is kept as
+  canonical; extract_session_report.py gains the guard. No golden diff: the
+  corpus's `tool_use`/`tool_result` blocks all carry string ids.
+
+- **track_edit** (0.58) and **track_bash** (0.42), plus the `EDIT_TOOLS`
+  constant both need. session_extract.py's copies keyed `verify_edited_since`/
+  `last_verify_norm` by `sid` inside a dict that is itself RESET at the top
+  of every per-file loop iteration — session-keying inside an already-
+  per-file-reset dict is redundant: exactly one `sessionId` ever appears in
+  one transcript file (the #1991 bug the sid-keying was originally built to
+  prevent — a review panel's siblings sharing their parent's `sessionId` and
+  scoring each other's retries — is already fully prevented by the per-file
+  reset alone, verified by `tests/repo/test_session_extract_subagents.py::
+  test_sibling_agents_running_one_command_are_not_retries`, which stays
+  green under this simplification). `extract_session_report.py`'s copies
+  already used the simpler flat per-thread dict
+  (`{"bash_commands", "last_verify_norm", "edited_since_verify"}`, built by
+  `new_thread()` below) with the same per-file-reset discipline. The simpler
+  form is kept as canonical (Simplicity First: no observable behavior
+  difference on any realistic transcript, confirmed by the golden harness);
+  `session_extract.py` drops its `sid`-keyed dicts and adopts `new_thread()`.
+
+- **detect_correction_turn** (0.78 — closest of the seven). Logic identical
+  between the two copies; moved verbatim.
+
+## Historical `session-digest.jsonl` comparability
+
+`by_agent_type`'s value shape changes from a bare integer (message count) to
+the same bucket-dict shape `extract_session_report.py` already emitted:
+`{input_tokens, cache_creation_input_tokens, cache_read_input_tokens,
+output_tokens, messages, dispatches, context_tokens, context_per_dispatch}`.
+Any historical `session-digest.jsonl` row is NOT comparable on
+`token.by_agent_type` (and the derived `session-sync` `by_thread` field)
+against a row produced after this change — a consumer doing
+`by_agent_type[x] == N` or arithmetic on the value breaks. This is the same
+shape of jump `session-digest/v2` (#1994) already made once. The formal
+schema-version bump (`session-digest/v3`) and any migration/split-on-schema
+consumer update is explicitly issue #2045's job, not this slice's — this
+slice only flags it, per its own acceptance criteria.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+from session_log import classify, redact
+
+#: Tools whose `tool_use` counts as an "edit" for rework tracking. Not one
+#: of ADR 0036's 14 classify.py symbols, but tightly coupled to the edit/
+#: bash signal functions below, so it lives here rather than in classify.py.
+EDIT_TOOLS = {"Edit", "Write", "NotebookEdit", "MultiEdit"}
+
+#: The usage fields that make up a dispatch's CONTEXT — what it carried in,
+#: as opposed to what it generated. Session telemetry puts ~90% of spend
+#: here (cache read + cache write), which is why per-agent context is the
+#: figure a panel-cost decision needs and `output_tokens` is tracked
+#: separately. Ported verbatim from extract_session_report.py (#2029).
+CONTEXT_TOKEN_FIELDS = (
+    "input_tokens",
+    "cache_creation_input_tokens",
+    "cache_read_input_tokens",
+)
+
+#: Mirrors `hooks/lib/cost_meter.py`'s `_new_bucket()` shape (#1094) so the
+#: per-agent breakdowns agree on field names across the plugin. They stay
+#: separate implementations — cost_meter runs live per turn, this runs over
+#: a whole transcript tree.
+AGENT_BUCKET_FIELDS = (*CONTEXT_TOKEN_FIELDS, "output_tokens")
+
+
+def new_agent_bucket() -> dict:
+    bucket = {f: 0 for f in AGENT_BUCKET_FIELDS}
+    bucket["messages"] = 0
+    bucket["dispatches"] = 0
+    return bucket
+
+
+def merge_agent_buckets(dest: dict, src: dict) -> None:
+    """Fold one project's per-agent buckets into cross-project totals.
+
+    Re-sums the raw fields rather than the derived ones: adding two
+    projects' `context_per_dispatch` values would produce a number that is
+    not a mean of anything. The derived figures are recomputed once, after
+    the merge."""
+    for label, bucket in (src or {}).items():
+        if not isinstance(bucket, dict):
+            # A digest written before this port (or before #2010 downstream)
+            # carries an int (a message count). Merging it as tokens would
+            # silently corrupt the total, so the label is preserved at zero
+            # rather than guessed at.
+            dest.setdefault(label, new_agent_bucket())
+            continue
+        into = dest.setdefault(label, new_agent_bucket())
+        for field in (*AGENT_BUCKET_FIELDS, "messages", "dispatches"):
+            into[field] += bucket.get(field, 0) or 0
+
+
+def finalize_agent_buckets(by_agent_type: dict) -> dict:
+    """Add the derived per-dispatch figure each bucket exists to answer.
+
+    `context_tokens` is the sum a dispatch is charged for carrying;
+    `context_per_dispatch` divides it by real dispatch count, which is why
+    dispatches are counted from subagent transcripts rather than messages.
+    It is `None` for `main` and for any agent with no counted dispatch — a
+    division that has no meaning must read as absent, not as 0, which would
+    rank a never-dispatched agent as the cheapest in the table."""
+    out = {}
+    for label, b in sorted(by_agent_type.items()):
+        context = sum(b[f] for f in CONTEXT_TOKEN_FIELDS)
+        entry = dict(b)
+        entry["context_tokens"] = context
+        entry["context_per_dispatch"] = (
+            round(context / b["dispatches"]) if b["dispatches"] else None
+        )
+        out[label] = entry
+    return out
+
+
+def accumulate_token_signals(usage_fields: dict, model, tokens_total, by_model) -> None:
+    """Token-accounting CORE: sum `usage_fields` (already read through
+    `session_log.records.usage_fields`) into `tokens_total` and
+    `by_model[model]`. No cost, no skill attribution — those stay
+    session_extract.py-only extensions (pricing/cost stays forked, ADR
+    0036); see this module's docstring."""
+    for f, v in usage_fields.items():
+        tokens_total[f] += v
+        if model:
+            by_model[model][f] += v
+
+
+def accumulate_skill_agent_signals(
+    skill,
+    content,
+    skills_invoked: Counter,
+    agent_dispatches: Counter,
+    active: dict[str, str | tuple[str, str] | None],
+) -> None:
+    """Skill/agent-detection concern. `skill` is the legacy attributionSkill
+    tag (kept as a fallback — real transcripts don't emit it, #182);
+    `content`'s tool_use blocks are the primary signal: the Skill tool and
+    the Agent/Task tool that actually invoke them (#182). `active` tracks
+    the most-recently-invoked skill/agent (#711), sticky until superseded,
+    for the correction-turn concern to attribute against. `active["last"]`
+    (#2013) is the same pointer collapsed to a single `(kind, name)` tuple
+    (or absent, before any dispatch) -- the ONE most-recently-dispatched
+    entity between the two, for `session_log.corrections`' `component`
+    field, which needs a single answer rather than two independently-sticky
+    ones.
+
+    Counts DISPATCHES, not runs: a dispatch made from inside a subagent is
+    only visible in that subagent's own transcript, and a dispatch whose
+    transcript is absent never ran. Run counts come from `attributionAgent`
+    (#1994)."""
+    if skill:
+        skills_invoked[redact.redact(skill)] += 1
+    if not isinstance(content, list):
+        return
+    for block in content:
+        if not isinstance(block, dict) or block.get("type") != "tool_use":
+            continue
+        name = block.get("name", "?")
+        inp = block.get("input", {}) if isinstance(block.get("input"), dict) else {}
+        if name == "Skill":
+            s = inp.get("skill") or inp.get("name")
+            if isinstance(s, str) and s:
+                active["skill"] = redact.redact(classify.strip_ns(s))
+                skills_invoked[active["skill"]] += 1
+                active["last"] = ("skill", active["skill"])
+        elif name in ("Agent", "Task"):
+            a = inp.get("subagent_type")
+            if isinstance(a, str) and a:
+                active["agent"] = redact.redact(classify.strip_ns(a))
+                agent_dispatches[active["agent"]] += 1
+                active["last"] = ("agent", active["agent"])
+
+
+def track_tool_call(block: dict, pending_tool: dict[str, str], tool_calls: Counter) -> None:
+    """Error-classification bookkeeping: count every tool invocation (the
+    error-rate denominator) and remember its id -> name so a later
+    tool_result can be attributed back to the tool that produced it."""
+    name = redact.redact(str(block.get("name", "?")))
+    tool_calls[name] += 1
+    bid = block.get("id")
+    if isinstance(bid, str) and bid:
+        pending_tool[bid] = name
+
+
+def classify_tool_result(
+    block: dict,
+    pending_tool: dict[str, str],
+    tool_errors: Counter,
+    error_counts: Counter,
+) -> None:
+    """Error-classification concern: tally errors by tool, and detect the
+    two rework sub-signals (failed edits via old_string mismatches, and
+    permission denials) from a tool_result block."""
+    if not block.get("is_error"):
+        return
+    bid = block.get("tool_use_id")
+    tool_name = pending_tool.get(bid, "?") if isinstance(bid, str) else "?"
+    tool_errors[tool_name] += 1
+    rcontent = classify.text_of(block.get("content"))
+    if tool_name in EDIT_TOOLS and classify.OLDSTRING_RE.search(rcontent):
+        error_counts["failed_edits"] += 1
+    if classify.PERMISSION_RE.search(rcontent):
+        error_counts["permission_denials"] += 1
+
+
+def new_thread() -> dict:
+    """Per-transcript-file state for `track_edit`/`track_bash`. One
+    transcript file is one thread of execution: a main-thread session, or a
+    single dispatched agent's run. Reset at the top of each file's
+    processing loop."""
+    return {"bash_commands": Counter(), "last_verify_norm": None, "edited_since_verify": False}
+
+
+def track_edit(block: dict, edits_per_file: Counter, thread: dict) -> None:
+    """Edit-tracking concern: count Edit/Write/... calls per file basename,
+    so repeated edits to the same file (a rework signal) can be derived.
+    Also marks this thread's pending stuck-verify-loop streak (#708) as
+    consumed — an edit resets it, same as verify_guard.py's own reset."""
+    name = block.get("name", "?")
+    inp = block.get("input", {}) if isinstance(block.get("input"), dict) else {}
+    if name in EDIT_TOOLS and inp.get("file_path"):
+        edits_per_file[redact.redact(str(inp["file_path"]), from_path=True)] += 1
+    if name in EDIT_TOOLS:
+        thread["edited_since_verify"] = True
+
+
+def track_bash(
+    block: dict,
+    bash_signal_counts: Counter,
+    thread: dict,
+    *,
+    active: dict | None = None,
+    retried_by_skill: Counter | None = None,
+    retried_by_agent: Counter | None = None,
+) -> None:
+    """Bash-retry / commit-bypass / stuck-verify-loop concern (#111, #708):
+    normalize the command for near-identical retry detection, detect a
+    stuck-verify-loop repeat (the same normalized verify command run again
+    with no Edit/Write/... call since the previous run in this thread), and
+    detect the review-gate bypass signal on `git commit` invocations.
+
+    Bash signals are scoped to ONE thread of execution (`thread`, a
+    per-transcript-file dict). Retries and repeated verify runs are only
+    meaningful within a thread: a review panel's sibling agents share their
+    parent's sessionId, so a session-keyed tally would score fifteen agents
+    each running `git diff --cached` once as fourteen retries.
+
+    `active`/`retried_by_skill`/`retried_by_agent` (#2110) attribute each
+    retry, at the moment it's detected, to whichever skill/agent is the
+    thread's current sticky pointer (`active["skill"]`/`active["agent"]`,
+    the same pointer `accumulate_skill_agent_signals` maintains and the
+    correction-turn signal already attributes against) — "unattributed"
+    when neither is set. All three are optional and default to no
+    attribution, so a caller with no `active` pointer to offer (there is
+    none today) gets the prior behavior unchanged."""
+    name = block.get("name", "?")
+    inp = block.get("input", {}) if isinstance(block.get("input"), dict) else {}
+    if name != "Bash" or not isinstance(inp.get("command"), str):
+        return
+    cmd = inp["command"].strip()
+    # near-identical retry detection: normalize whitespace
+    norm = re.sub(r"\s+", " ", cmd)
+    if active is not None and thread["bash_commands"][norm] >= 1:
+        # This exact normalized command already ran once in this thread —
+        # this call is a retry, attributed to whichever skill/agent is
+        # active right now.
+        if retried_by_skill is not None:
+            retried_by_skill[active.get("skill") or "unattributed"] += 1
+        if retried_by_agent is not None:
+            retried_by_agent[active.get("agent") or "unattributed"] += 1
+    thread["bash_commands"][norm] += 1
+    if classify.VERIFY_RE.search(cmd):
+        if thread["last_verify_norm"] == norm and not thread["edited_since_verify"]:
+            bash_signal_counts["repeated_verify_runs"] += 1
+        thread["last_verify_norm"] = norm
+        thread["edited_since_verify"] = False
+    # gate signal (#111): commit + review-gate bypass, scoped to the
+    # git-commit argv (#2036) — see classify.bash_segments()/is_git_commit_argv().
+    for segment in classify.bash_segments(cmd):
+        if classify.is_git_commit_argv(segment):
+            bash_signal_counts["commit_attempts"] += 1
+            if any(tok in classify.COMMIT_BYPASS_TOKENS for tok in segment[1:]):
+                bash_signal_counts["commit_bypasses"] += 1
+
+
+def detect_correction_turn(rec: dict, content) -> bool:
+    """Correction-turn concern: a real user message (not a tool_result
+    envelope) containing a correction keyword ("no", "actually", "revert",
+    ...)."""
+    if rec.get("type") != "user" or rec.get("isMeta"):
+        return False
+    utext = classify.text_of(content)
+    if not utext:
+        return False
+    # skip pure tool_result envelopes (no free-text user prompt)
+    if isinstance(content, list) and all(
+        isinstance(b, dict) and b.get("type") == "tool_result" for b in content
+    ):
+        return False
+    return bool(classify.CORRECTION_RE.search(utext.lower()))