feat: support generic metadata in agent notifications

Add an optional `metadata` field (freeform JSON object) to agent
notifications. The daemon stores and returns it verbatim — no
interpretation, pure pass-through.

This allows hooks to attach arbitrary context (terminal emulator info,
git branch, workspace labels, etc.) that consumers like arbor-tui can
read without coupling the daemon to specific use cases.

Closes #85

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: edmondop

crates/arbor-daemon-client/src/types.rs

@@ -106,6 +106,8 @@ pub struct AgentSessionDto {
     pub cwd: String,
     pub state: String,
     pub updated_at_unix_ms: u64,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
@@ -114,6 +116,7 @@ struct AgentSessionDtoWire {
     cwd: String,
     state: String,
     updated_at_unix_ms: u64,
+    metadata: Option<serde_json::Value>,
 }
 
 fn legacy_agent_session_id(cwd: &str) -> String {
@@ -133,6 +136,7 @@ impl<'de> Deserialize<'de> for AgentSessionDto {
             cwd: wire.cwd,
             state: wire.state,
             updated_at_unix_ms: wire.updated_at_unix_ms,
+            metadata: wire.metadata,
         })
     }
 }
@@ -317,5 +321,53 @@ mod tests {
         assert_eq!(dto.cwd, "/tmp/repo/worktree");
         assert_eq!(dto.state, "waiting");
         assert_eq!(dto.updated_at_unix_ms, 99);
+        assert!(dto.metadata.is_none());
+    }
+
+    #[test]
+    fn agent_session_dto_deserializes_with_metadata() {
+        let dto: AgentSessionDto = serde_json::from_value(serde_json::json!({
+            "session_id": "sess-1",
+            "cwd": "/tmp/test",
+            "state": "working",
+            "updated_at_unix_ms": 42_u64,
+            "metadata": {
+                "terminal": { "type": "tmux", "server": "my-project", "pane_id": "%42" },
+                "git": { "branch": "feat/cool" }
+            }
+        }))
+        .expect("payload with metadata should deserialize");
+
+        let meta = dto.metadata.expect("metadata should be Some");
+        assert_eq!(meta["terminal"]["type"], "tmux");
+        assert_eq!(meta["terminal"]["server"], "my-project");
+        assert_eq!(meta["terminal"]["pane_id"], "%42");
+        assert_eq!(meta["git"]["branch"], "feat/cool");
+    }
+
+    #[test]
+    fn agent_session_dto_without_metadata_omits_field_in_json() {
+        let dto = AgentSessionDto {
+            session_id: "s1".to_owned(),
+            cwd: "/tmp".to_owned(),
+            state: "idle".to_owned(),
+            updated_at_unix_ms: 0,
+            metadata: None,
+        };
+        let json = serde_json::to_value(&dto).expect("should serialize");
+        assert!(json.get("metadata").is_none(), "metadata should be omitted when None");
+    }
+
+    #[test]
+    fn agent_session_dto_with_metadata_includes_field_in_json() {
+        let dto = AgentSessionDto {
+            session_id: "s2".to_owned(),
+            cwd: "/tmp".to_owned(),
+            state: "working".to_owned(),
+            updated_at_unix_ms: 1,
+            metadata: Some(serde_json::json!({"foo": "bar"})),
+        };
+        let json = serde_json::to_value(&dto).expect("should serialize");
+        assert_eq!(json["metadata"]["foo"], "bar");
     }
 }

crates/arbor-httpd/src/routes.rs

@@ -1206,6 +1206,7 @@ pub(crate) async fn agent_notify(
         request.session_id.clone(),
         request.cwd.clone(),
         agent_state,
+        request.metadata.clone(),
         AgentSessionUpdateSource::Hook,
     )
     .await;
@@ -1225,6 +1226,7 @@ pub(crate) async fn apply_terminal_activity_event(state: &AppState, event: Termi
                 terminal_agent_session_key(&session_id),
                 cwd.display().to_string(),
                 agent_state,
+                None,
                 AgentSessionUpdateSource::TerminalActivity,
             )
             .await;
@@ -1240,6 +1242,7 @@ async fn upsert_agent_session(
     session_id: String,
     cwd: String,
     agent_state: AgentState,
+    metadata: Option<serde_json::Value>,
     source: AgentSessionUpdateSource,
 ) {
     let now_ms = SystemTime::now()
@@ -1260,6 +1263,7 @@ async fn upsert_agent_session(
             cwd: cwd.clone(),
             state: agent_state,
             updated_at_unix_ms: now_ms,
+            metadata: metadata.clone(),
         });
 
         (
@@ -1268,6 +1272,7 @@ async fn upsert_agent_session(
                 cwd: cwd.clone(),
                 state: agent_state_label(agent_state).to_owned(),
                 updated_at_unix_ms: now_ms,
+                metadata,
             },
             previous_state,
         )
@@ -1663,6 +1668,7 @@ fn agent_session_snapshot(sessions: &mut HashMap<String, AgentSession>) -> Vec<A
                 AgentState::Waiting => "waiting".to_owned(),
             },
             updated_at_unix_ms: session.updated_at_unix_ms,
+            metadata: session.metadata.clone(),
         })
         .collect();
     snapshot.sort_by(|left, right| {

crates/arbor-httpd/src/types.rs

@@ -39,13 +39,15 @@ pub(crate) struct AgentSession {
     pub(crate) cwd: String,
     pub(crate) state: AgentState,
     pub(crate) updated_at_unix_ms: u64,
+    pub(crate) metadata: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Clone, Deserialize)]
 pub(crate) struct AgentNotifyRequest {
     pub(crate) hook_event_name: String,
     pub(crate) session_id: String,
     pub(crate) cwd: String,
+    pub(crate) metadata: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Clone, Serialize)]

crates/arbor-mcp/src/lib.rs

@@ -579,6 +579,7 @@ mod tests {
                 cwd: "/tmp/repo".to_owned(),
                 state: "working".to_owned(),
                 updated_at_unix_ms: 1,
+                metadata: None,
             }])
         }