feat(bridge): tool call statistics from transcript parsing

[fagemx]

Context

Chronicle 模型效能分析需要知道代理的工具調用分布。
edda-transcript 已能解析 transcript，但不統計 tool calls。

數據需求

每個 session 的工具調用統計：

{
  "session_id": "...",
  "tool_calls": {
    "Read": 15,
    "Edit": 8,
    "Bash": 12,
    "Grep": 6,
    "Glob": 3,
    "Write": 2,
    "Agent": 4
  },
  "total": 50,
  "edit_ratio": 0.20,
  "search_ratio": 0.48
}

用途

• 模型行為 pattern（Opus vs Sonnet 的工具偏好）
• 效率分析（search_ratio 高 = 在探索，edit_ratio 高 = 在產出）
• 活動分類輔助（search 多 = research，edit 多 = implement）

實作方向

• 在 edda-transcript 的 delta 處理中加入 tool call 計數
• session 結束時寫入 summary event
• 或在 AssistantResponse hook 中累加

驗收標準

• session summary 包含 tool call breakdown
• edda log --type session 顯示工具調用數
• 可按 tool 類型查詢

Phase

Phase 1.5 — enrichment

[fagemx]

Research Phase: Tool Call Statistics from Transcript Parsing (#160)

Executive Summary

The majority of the requested functionality already exists. The codebase has comprehensive tool call counting, per-tool breakdown, edit/search ratios, and session digest integration. The issue's acceptance criteria need to be mapped against what's already implemented.

Current State Analysis

1. Transcript-Level Tool Call Extraction (DONE)

File: crates/edda-transcript/src/ingest.rs

IngestStats already contains tool_calls_by_name: HashMap<String, usize> (line 25). During ingest, every assistant record is scanned for tool_use content blocks, and each tool's name is counted in extract_tool_calls() (lines 230-244). This is exercised by ingest_extracts_tool_calls_from_assistant test.

However, this transcript-level stat is not consumed by any downstream code. The ingest_and_build_pack() function in dispatch.rs calls ingest_transcript_delta() but discards the return value (let _ = ... at line 279).

2. Session Ledger-Level Tool Call Counting (DONE)

File: crates/edda-bridge-claude/src/digest.rs

SessionStats (line 53-94) has:

• tool_calls: u64 -- total count
• tool_call_breakdown: BTreeMap<String, u64> -- per-tool counts

extract_stats() (line 97) reads the session ledger (not the transcript) -- the JSONL file at {project_dir}/ledger/{session_id}.jsonl where hook envelopes are appended. Each PostToolUse event increments the count and records the tool name.

3. Digest Event Generation (DONE)

File: crates/edda-bridge-claude/src/digest.rs

build_digest_event() (line 393) writes tool_call_breakdown, edit_ratio, and search_ratio into the event payload under session_stats. The text summary includes "Tools: Read:15 Edit:8..." and "edit_ratio: 0.20, search_ratio: 0.48".

4. CLI Display (DONE)

File: crates/edda-cli/src/cmd_log.rs

format_session_digest_detail() (line 282) displays the breakdown and ratios when running edda log --type session.

5. Tool-Based Querying (DONE)

File: crates/edda-cli/src/cmd_log.rs

LogParams has a tool: Option<&str> field (line 15), and matches_filter() checks for session_stats.tool_call_breakdown[tool] > 0 (lines 122-135). This enables edda log --tool Read.

Acceptance Criteria Mapping

Criterion	Status	Evidence
session summary contains tool call breakdown	DONE	build_digest_event() writes tool_call_breakdown + ratios into payload
edda log --type session shows tool call counts	DONE	format_session_digest_detail() renders breakdown + ratios
Queryable by tool type	DONE	--tool filter in LogParams + matches_filter()

Gap Analysis

Gap 1: Transcript-Level Stats Are Discarded

The IngestStats.tool_calls_by_name from edda_transcript::ingest_transcript_delta is not consumed -- the return value is ignored in ingest_and_build_pack(). This is not a bug because tool counts are independently derived from the session ledger via extract_stats(). However, the two sources could diverge:

• Session ledger counts PostToolUse hook events (what Claude Code sends back)
• Transcript counts tool_use content blocks inside assistant messages (what the model generates)

These should match 1:1, but the transcript path provides a more direct source. Currently the redundancy is harmless.

Gap 2: No Cumulative Tool Stats Across Sessions

The issue's JSON example shows session_id scoped stats. There's no cross-session aggregation (e.g., "over all sessions, how many Read calls total?"). This isn't in the acceptance criteria, so it's out of scope, but worth noting for future Chronicle integration.

Gap 3: SessionDigestEntry in edda-derive Lacks Breakdown

File: crates/edda-derive/src/types.rs

SessionDigestEntry has tool_calls: u64 but no tool_call_breakdown field. This means the derive layer (used for branch snapshots and context injection) only sees the total count, not the per-tool breakdown. This limits downstream consumers (e.g., edda-ask, L2 narrative) from accessing tool distribution data.

Gap 4: PrevDigest Lacks Tool Breakdown

File: crates/edda-bridge-claude/src/digest.rs lines 1248-1288

PrevDigest does not include tool_call_breakdown or ratios. The next session's context injection via "Previous Session" section won't show tool distribution from the prior session.

Data Flow Diagram

Claude Code -> hook stdin -> dispatch.rs:hook_entrypoint_from_stdin()
  |
  append_to_session_ledger() -> {project}/ledger/{session_id}.jsonl
  |
  Also: ingest_transcript_delta() -> {project}/transcripts/{session_id}.jsonl
       (tool_calls_by_name populated but return value discarded)
  |
SessionEnd/SessionStart:
  extract_stats() reads session ledger -> SessionStats.tool_call_breakdown
  |
  build_digest_event() -> workspace ledger event with session_stats.tool_call_breakdown
  |
  edda log --type session -> format_session_digest_detail() -> CLI output
  edda log --tool Read -> matches_filter() -> filtered CLI output

Key Files

• crates/edda-transcript/src/ingest.rs -- transcript-level tool extraction
• crates/edda-bridge-claude/src/digest.rs -- session stats extraction and digest event
• crates/edda-bridge-claude/src/dispatch.rs -- hook orchestration
• crates/edda-cli/src/cmd_log.rs -- CLI display and filtering
• crates/edda-derive/src/types.rs -- downstream data structures

Conclusion

The core feature described in issue #160 is already implemented. The remaining work is:

1. Closing minor gaps in data propagation (SessionDigestEntry, PrevDigest)
2. Potentially consuming transcript-level stats (or acknowledging the session-ledger path as canonical)
3. Verifying end-to-end correctness with integration tests

[fagemx]

Innovation Phase: Tool Call Statistics from Transcript Parsing (#160)

Situation Recap

The core tool call statistics feature is already implemented across the session ledger, digest events, CLI display, and tool-based filtering. The remaining work is about closing data propagation gaps and deciding the canonical data source.

Approach A: Close Gaps Only (Minimal)

What: Add tool_call_breakdown to SessionDigestEntry and PrevDigest, then close the issue.

Changes:

1. Add tool_call_breakdown: BTreeMap<String, u64>, edit_ratio: f64, search_ratio: f64 to SessionDigestEntry in edda-derive/src/types.rs
2. Update the snapshot parser in edda-derive/src/snapshot.rs to extract these fields
3. Add tool_call_breakdown: BTreeMap<String, u64> to PrevDigest
4. Update write_prev_digest() to include the breakdown

Pros:

• Minimal code changes (4 files, ~30 lines)
• No behavioral changes to existing working code
• Closes all gaps immediately

Cons:

• Doesn't address the transcript-level stats being unused (minor technical debt)
• PrevDigest size grows (but negligibly -- a few extra JSON keys)

Risk: Very low. All changes are additive to existing serialized structs with #[serde(default)].

Approach B: Unify Data Source (Session Ledger = Canonical)

What: Keep session ledger as the single source of truth for tool call stats, explicitly remove the unused transcript-level counting to reduce confusion.

Changes:

1. Same as Approach A (gap closure)
2. Remove tool_calls_by_name from IngestStats
3. Remove extract_tool_calls() from ingest.rs
4. Remove corresponding test

Pros:

• Eliminates dual counting paths -- reduces confusion
• Less code to maintain

Cons:

• Breaks the principle of keeping transcript-level data self-contained. The edda-transcript crate is designed to be usable independently of the bridge
• Removes a feature that could be useful for non-Claude-bridge transcript consumers
• The transcript data is already there; removing it loses information

Risk: Medium. Removing a public field from IngestStats is a breaking change for the crate's API.

Approach C: Enrich with Transcript-Level Stats (Additive)

What: Actually consume the transcript-level tool_calls_by_name as a complement to session ledger stats.

Changes:

1. Same as Approach A (gap closure)
2. In ingest_and_build_pack(), capture the IngestStats return value
3. Write tool_calls_by_name to a state file (e.g., state/tool_calls.{session_id}.json)
4. At digest time, merge transcript-level counts with session-ledger counts as a cross-validation

Pros:

• Uses both data sources, enabling future cross-validation
• Transcript data captures tools that might not fire PostToolUse hooks (edge cases)

Cons:

• Added complexity for marginal benefit
• Two sources of the same data that should agree -- cross-validation is overkill
• Extra state file per session

Risk: Low technically, but over-engineered for the current need.

Evaluation Matrix

Criterion	A (Minimal)	B (Unify)	C (Enrich)
Acceptance criteria met	Yes (already met)	Yes (already met)	Yes (already met)
Gap closure	Full	Full	Full
Code simplicity	Best	Good	Worst
Breaking changes	None	IngestStats API	None
Future extensibility	Good	Limited	Best
Effort	~2hr	~3hr	~4hr

Recommendation: Approach A (Close Gaps Only)

Rationale:

1. The acceptance criteria are already met. This is a "polish and close" issue, not a new feature build.
2. The transcript-level stats aren't hurting anything -- leave them for potential future use.
3. The gaps in SessionDigestEntry and PrevDigest are genuine limitations that downstream consumers will eventually hit.
4. Minimal change = minimal risk of regression in a critical path (session lifecycle).

Innovation: Beyond the Issue

If we want to extend tool call analytics beyond what's asked:

Future: Cross-Session Aggregation (for Chronicle)

• Add edda stats CLI subcommand that aggregates tool_call_breakdown across all session digest events
• Output model-specific profiles (Opus vs Sonnet tool distribution)
• This is not in scope for this issue but is the natural next step mentioned in the issue's "Usage" section

Future: Activity Classification

• The edit_ratio and search_ratio already computed could be used to auto-classify sessions as "research", "implement", "debug" etc.
• This could be added to PrevDigest.activity_type for next-session context
• Again, out of scope but worth tracking as a follow-up issue

[fagemx]

Plan Phase: Tool Call Statistics from Transcript Parsing (#160)

Summary

All three acceptance criteria are already implemented. This plan addresses the remaining data propagation gaps identified in the research phase, using Approach A (Close Gaps Only).

Pre-Implementation Verification

Before any code changes, verify the existing implementation works end-to-end:

cd crates/edda-transcript && cargo test ingest_extracts_tool_calls
cd crates/edda-bridge-claude && cargo test digest_counts_tools digest_tool_breakdown_in_payload

If these pass, the core feature is confirmed working.

Implementation Steps

Step 1: Add tool_call_breakdown to SessionDigestEntry

File: crates/edda-derive/src/types.rs

Add three fields to SessionDigestEntry:

pub struct SessionDigestEntry {
    // ... existing fields ...
    /// Per-tool call counts (e.g. "Read" -> 15, "Edit" -> 8).
    pub tool_call_breakdown: std::collections::BTreeMap<String, u64>,
    /// Ratio of edit tools (Edit, Write) to total tool calls.
    pub edit_ratio: f64,
    /// Ratio of search tools (Read, Grep, Glob) to total tool calls.
    pub search_ratio: f64,
}

Step 2: Parse breakdown in snapshot builder

File: crates/edda-derive/src/snapshot.rs (around line 191-265)

After the existing notes field extraction, add:

tool_call_breakdown: stats
    .and_then(|s| s.get("tool_call_breakdown"))
    .and_then(|x| x.as_object())
    .map(|obj| {
        obj.iter()
            .filter_map(|(k, v)| v.as_u64().map(|c| (k.clone(), c)))
            .collect()
    })
    .unwrap_or_default(),
edit_ratio: stats
    .and_then(|s| s.get("edit_ratio"))
    .and_then(|x| x.as_f64())
    .unwrap_or(0.0),
search_ratio: stats
    .and_then(|s| s.get("search_ratio"))
    .and_then(|x| x.as_f64())
    .unwrap_or(0.0),

Step 3: Add tool_call_breakdown to PrevDigest

File: crates/edda-bridge-claude/src/digest.rs

Add to PrevDigest struct:

/// Per-tool call counts (e.g. "Read" -> 15, "Edit" -> 8).
#[serde(default)]
pub tool_call_breakdown: BTreeMap<String, u64>,
/// Ratio of edit tools (Edit, Write) to total tool calls.
#[serde(default)]
pub edit_ratio: f64,
/// Ratio of search tools (Read, Grep, Glob) to total tool calls.
#[serde(default)]
pub search_ratio: f64,

Step 4: Populate PrevDigest breakdown in write_prev_digest()

File: crates/edda-bridge-claude/src/digest.rs

In the write_prev_digest() function, add to the PrevDigest construction:

let (edit_ratio, search_ratio) = compute_tool_ratios(&stats.tool_call_breakdown, stats.tool_calls);
let digest = PrevDigest {
    // ... existing fields ...
    tool_call_breakdown: stats.tool_call_breakdown.clone(),
    edit_ratio,
    search_ratio,
};

Step 5: Add tests

File: crates/edda-derive/src/snapshot.rs (test module)

Add a test that verifies SessionDigestEntry.tool_call_breakdown is populated from a workspace ledger event containing tool call data.

File: crates/edda-bridge-claude/src/digest.rs (test module)

Add a test to prev_digest_roundtrip or create a new test prev_digest_has_tool_breakdown that verifies the breakdown survives write/read.

Step 6: Verify all existing tests still pass

cd crates/edda-transcript && cargo test
cd crates/edda-bridge-claude && cargo test
cd crates/edda-derive && cargo test
cd crates/edda-cli && cargo test

Files Changed

File	Change Type	Description
crates/edda-derive/src/types.rs	Modify	Add 3 fields to SessionDigestEntry
crates/edda-derive/src/snapshot.rs	Modify	Parse breakdown + ratios from event payload
crates/edda-bridge-claude/src/digest.rs	Modify	Add 3 fields to PrevDigest, populate in write_prev_digest()

What This Does NOT Change

• The session ledger remains the canonical source for tool call stats (via PostToolUse hook events)
• The transcript-level tool_calls_by_name in IngestStats stays as-is (useful for potential future use)
• No changes to ingest.rs, dispatch.rs, or cmd_log.rs -- they already work correctly
• No new CLI flags or subcommands needed

Test Strategy

1. Unit tests: Add test for SessionDigestEntry breakdown parsing (snapshot.rs), PrevDigest roundtrip with breakdown (digest.rs)
2. Existing test regression: Run full test suite for edda-transcript, edda-bridge-claude, edda-derive, edda-cli
3. Manual verification: After changes, run edda log --type session and edda log --tool Edit on a real project to confirm output

Risk Assessment

• Backward compatibility: All new fields use #[serde(default)] or unwrap_or_default(). Old digest events without these fields will parse correctly with default values.
• Performance: No additional I/O or computation. The data already exists in the event payload; we're just propagating it to more struct fields.
• Scope creep: Explicitly out of scope: cross-session aggregation, activity classification, and removing transcript-level counting.

Estimated Effort

~1-2 hours total. The changes are mechanical: adding struct fields and their corresponding parsers/writers, plus tests.

[fagemx]

Work completed. PR created: #167

All CI checks pending — 528 tests pass locally across edda-derive (42), edda-bridge-claude (343), and edda (143).