feat: WatcherEvent convenience methods and provider-namespaced extras

toolpath-convo 0.5.0:
- Added as_turn(), as_progress(), is_update(), turn_id() on WatcherEvent
- Documented Turn.extra provider-namespacing convention

toolpath-claude 0.6.2:
- Populate Turn.extra["claude"] from ConversationEntry.extra
- Enrich Progress.data["claude"] with full entry payload
- Both additive — previously-empty fields now carry data

Author: akesling

CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the Toolpath workspace are documented here.
 
+## 0.5.0 — toolpath-convo / 0.6.2 — toolpath-claude
+
+### toolpath-convo 0.5.0
+
+- Added `WatcherEvent::as_turn()` — returns the `Turn` payload for both `Turn` and `TurnUpdated` variants
+- Added `WatcherEvent::as_progress()` — returns `(kind, data)` for `Progress` events
+- Added `WatcherEvent::is_update()` — returns `true` only for `TurnUpdated`
+- Added `WatcherEvent::turn_id()` — returns the turn ID for turn-carrying variants
+- Added dispatch loop example to `WatcherEvent` rustdoc
+
+### toolpath-claude 0.6.2
+
+- `to_turn()` now populates `Turn.extra["claude"]` with provider-specific metadata from `ConversationEntry.extra` (e.g. `subtype`, `data`), enabling trait-only consumers to access state-inference signals without importing provider types
+- `WatcherEvent::Progress` events now include the full entry payload under `data["claude"]`, carrying fields like `data.type`, `data.hookName`, `data.agentId`, and `data.message` that were previously discarded
+- Both changes are additive — previously-empty fields are now populated; no existing behavior changes
+- Thanks to the crabcity maintainers for the detailed gap analysis
+
 ## 0.6.1 — toolpath-claude
 
 ### toolpath-claude 0.6.1

CLAUDE.md

@@ -123,3 +123,4 @@ Build the site after changes: `cd site && pnpm run build` (should produce 7 page
 - The git derivation (`toolpath-git`) uses `git2` (libgit2 bindings), not shelling out to git
 - Claude conversation data lives in `~/.claude/projects/` as JSONL files; `toolpath-claude` reads these directly
 - `toolpath-claude` follows session chains by default — Claude Code rotates JSONL files on context overflow; `read_conversation` merges segments, `list_conversations` returns chain heads. `read_segment`/`list_segments` for single-file access. `ChainIndex` makes this incremental.
+- Provider-specific extras convention: `Turn.extra` and `WatcherEvent::Progress.data` use provider-namespaced keys (e.g. `extra["claude"]`). `toolpath-claude` populates `Turn.extra["claude"]` from `ConversationEntry.extra` and `Progress.data["claude"]` from the full entry payload. This lets trait-only consumers access provider metadata (like `subtype` for state inference) without importing provider types.

Cargo.lock

@@ -15,9 +15,9 @@ license = "Apache-2.0"
 
 [workspace.dependencies]
 toolpath = { version = "0.1.5", path = "crates/toolpath" }
-toolpath-convo = { version = "0.4.0", path = "crates/toolpath-convo" }
+toolpath-convo = { version = "0.5.0", path = "crates/toolpath-convo" }
 toolpath-git = { version = "0.1.3", path = "crates/toolpath-git" }
-toolpath-claude = { version = "0.6.1", path = "crates/toolpath-claude", default-features = false }
+toolpath-claude = { version = "0.6.2", path = "crates/toolpath-claude", default-features = false }
 toolpath-dot = { version = "0.1.2", path = "crates/toolpath-dot" }
 
 serde = { version = "1.0", features = ["derive"] }

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "toolpath-claude"
-version = "0.6.1"
+version = "0.6.2"
 edition.workspace = true
 license.workspace = true
 repository = "https://github.com/empathic/toolpath"

crates/toolpath-claude/Cargo.toml

@@ -136,10 +136,20 @@ follows up with `WatcherEvent::TurnUpdated` when tool results arrive:
 use toolpath_convo::{ConversationWatcher, WatcherEvent};
 
 for event in watcher.poll()? {
-    match event {
-        WatcherEvent::Turn(turn) => ui.add_turn(*turn),
-        WatcherEvent::TurnUpdated(turn) => ui.replace_turn(*turn),
-        WatcherEvent::Progress { .. } => {}
+    match &event {
+        WatcherEvent::Turn(turn) => ui.add_turn(turn),
+        WatcherEvent::TurnUpdated(turn) => ui.replace_turn(turn),
+        WatcherEvent::Progress { kind, data } => {
+            match kind.as_str() {
+                "session_rotated" => ui.notify_rotation(&data["from"], &data["to"]),
+                _ => {
+                    // Provider-specific progress data under data["claude"]
+                    if let Some(claude) = data.get("claude") {
+                        ui.show_progress(kind, claude);
+                    }
+                }
+            }
+        }
     }
 }
 ```
@@ -179,6 +189,24 @@ cache read, cache write) into a single aggregate.
 `ConversationView.files_changed` lists all files mutated during the session
 (deduplicated, first-touch order), derived from `FileWrite`-categorized tool inputs.
 
+**Provider-specific metadata** — Claude log entries often carry extra fields
+(e.g. `subtype`, `data`) that don't map to the common `Turn` schema. These are
+forwarded into `Turn.extra["claude"]` so trait-only consumers can access them
+without importing Claude-specific types:
+
+```rust,ignore
+// State inference from provider metadata
+if let Some(claude) = turn.extra.get("claude") {
+    if claude.get("subtype").and_then(|v| v.as_str()) == Some("init") {
+        // This is a session initialization entry
+    }
+}
+```
+
+For `WatcherEvent::Progress` events, the full entry payload is similarly
+available under `data["claude"]` — carrying fields like `data.type`,
+`data.hookName`, `data.agentId`, and `data.message`.
+
 See [`toolpath-convo`](https://crates.io/crates/toolpath-convo) for the full trait and type definitions.
 
 ## Part of Toolpath

crates/toolpath-claude/README.md

@@ -5,6 +5,8 @@
 //! pairs them by `tool_use_id` so consumers get complete `Turn` values
 //! with `ToolInvocation.result` populated.
 
+use std::collections::HashMap;
+
 use crate::ClaudeConvo;
 use crate::types::{Conversation, ConversationEntry, Message, MessageContent, MessageRole};
 #[cfg(any(feature = "watcher", test))]
@@ -82,6 +84,17 @@ fn message_to_turn(entry: &ConversationEntry, msg: &Message) -> Turn {
 
     let delegations = extract_delegations(&tool_uses);
 
+    let extra = if entry.extra.is_empty() {
+        HashMap::new()
+    } else {
+        let mut map = HashMap::new();
+        map.insert(
+            "claude".to_string(),
+            serde_json::to_value(&entry.extra).unwrap_or_default(),
+        );
+        map
+    };
+
     Turn {
         id: entry.uuid.clone(),
         parent_id: entry.parent_uuid.clone(),
@@ -95,7 +108,7 @@ fn message_to_turn(entry: &ConversationEntry, msg: &Message) -> Turn {
         token_usage,
         environment,
         delegations,
-        extra: Default::default(),
+        extra,
     }
 }
 
@@ -280,13 +293,20 @@ fn extract_files_changed(turns: &[Turn]) -> Vec<String> {
 fn entry_to_watcher_event(entry: &ConversationEntry) -> WatcherEvent {
     match entry_to_turn(entry) {
         Some(turn) => WatcherEvent::Turn(Box::new(turn)),
-        None => WatcherEvent::Progress {
-            kind: entry.entry_type.clone(),
-            data: serde_json::json!({
+        None => {
+            let mut data = serde_json::json!({
                 "uuid": entry.uuid,
                 "timestamp": entry.timestamp,
-            }),
-        },
+            });
+            if !entry.extra.is_empty() {
+                data["claude"] =
+                    serde_json::to_value(&entry.extra).unwrap_or_default();
+            }
+            WatcherEvent::Progress {
+                kind: entry.entry_type.clone(),
+                data,
+            }
+        }
     }
 }
 
@@ -1119,6 +1139,64 @@ mod tests {
         );
     }
 
+    // ── Provider-specific extras (Turn.extra["claude"]) ─────────────
+
+    #[test]
+    fn test_turn_extra_populated_from_entry() {
+        let entry: ConversationEntry = serde_json::from_str(
+            r#"{"uuid":"u1","type":"user","timestamp":"2024-01-01T00:00:00Z","subtype":"init","message":{"role":"user","content":"hello"}}"#,
+        )
+        .unwrap();
+        let turn = to_turn(&entry).unwrap();
+        let claude = turn.extra.get("claude").expect("extra[\"claude\"] missing");
+        assert_eq!(claude["subtype"], "init");
+    }
+
+    #[test]
+    fn test_turn_extra_empty_when_no_extras() {
+        let entry: ConversationEntry = serde_json::from_str(
+            r#"{"uuid":"u1","type":"user","timestamp":"2024-01-01T00:00:00Z","message":{"role":"user","content":"hello"}}"#,
+        )
+        .unwrap();
+        let turn = to_turn(&entry).unwrap();
+        assert!(turn.extra.is_empty());
+    }
+
+    #[test]
+    fn test_progress_data_enriched_with_extras() {
+        let entry: ConversationEntry = serde_json::from_str(
+            r#"{"uuid":"u1","type":"progress","timestamp":"2024-01-01T00:00:00Z","data":{"type":"hook_progress","hookName":"pre-commit"}}"#,
+        )
+        .unwrap();
+        let event = entry_to_watcher_event(&entry);
+        match event {
+            WatcherEvent::Progress { kind, data } => {
+                assert_eq!(kind, "progress");
+                assert_eq!(data["uuid"], "u1");
+                assert_eq!(data["timestamp"], "2024-01-01T00:00:00Z");
+                let claude = &data["claude"];
+                assert_eq!(claude["data"]["type"], "hook_progress");
+                assert_eq!(claude["data"]["hookName"], "pre-commit");
+            }
+            other => panic!("Expected Progress, got {:?}", std::mem::discriminant(&other)),
+        }
+    }
+
+    #[test]
+    fn test_progress_data_no_claude_key_when_no_extras() {
+        let entry: ConversationEntry = serde_json::from_str(
+            r#"{"uuid":"u1","type":"progress","timestamp":"2024-01-01T00:00:00Z"}"#,
+        )
+        .unwrap();
+        let event = entry_to_watcher_event(&entry);
+        match event {
+            WatcherEvent::Progress { data, .. } => {
+                assert!(data.get("claude").is_none());
+            }
+            other => panic!("Expected Progress, got {:?}", std::mem::discriminant(&other)),
+        }
+    }
+
     #[test]
     fn test_no_delegations_for_non_task_tools() {
         let (_temp, provider) = setup_provider();

crates/toolpath-claude/src/provider.rs

@@ -1,6 +1,6 @@
 [package]
 name = "toolpath-convo"
-version = "0.4.0"
+version = "0.5.0"
 edition.workspace = true
 license.workspace = true
 repository = "https://github.com/empathic/toolpath"

crates/toolpath-convo/Cargo.toml

@@ -24,7 +24,7 @@ Write your conversation analysis once, swap providers without changing a line.
 | `TokenUsage` | Input/output/cache token counts |
 | `EnvironmentSnapshot` | Working directory and VCS branch/revision at time of a turn |
 | `DelegatedWork` | A sub-agent delegation: prompt, nested turns, result |
-| `WatcherEvent` | A `Turn` (new), `TurnUpdated` (enriched with tool results), or `Progress` event |
+| `WatcherEvent` | A `Turn` (new), `TurnUpdated` (enriched with tool results), or `Progress` event — with `as_turn()`, `as_progress()`, `is_update()`, `turn_id()` helpers for ergonomic dispatch |
 
 **Traits** define how providers expose their data:
 
@@ -101,6 +101,40 @@ let writes: Vec<_> = turn.tool_uses.iter()
     .collect();
 ```
 
+## Watching
+
+Dispatch on `WatcherEvent` with `match` — three variants, exhaustive:
+
+```rust,ignore
+use toolpath_convo::{ConversationWatcher, WatcherEvent};
+
+for event in watcher.poll()? {
+    match &event {
+        WatcherEvent::Turn(turn) => ui.add_turn(turn),
+        WatcherEvent::TurnUpdated(turn) => ui.replace_turn(turn),
+        WatcherEvent::Progress { kind, data } => ui.show_progress(kind, data),
+    }
+}
+```
+
+Convenience methods (`as_turn()`, `as_progress()`, `is_update()`, `turn_id()`)
+are available for cases where the distinction between `Turn` and `TurnUpdated`
+collapses — e.g. a formatting pipeline that takes a turn + flag:
+
+```rust,ignore
+// When Turn/TurnUpdated go through the same path:
+if let Some(turn) = event.as_turn() {
+    format_turn(turn, event.is_update());
+}
+
+// Keying/dedup without matching two variants:
+if let Some(id) = event.turn_id() {
+    seen.insert(id);
+}
+```
+
+Provider-specific metadata lives in `Turn.extra`, namespaced by provider (e.g. `turn.extra["claude"]`). This keeps the common schema clean while giving consumers opt-in access to provider internals.
+
 ## Provider implementations
 
 | Provider | Crate |