feat(#1021): query_agent_state capability for agent socket GetLooseEnds/CountPendingReminders/ReminderRollup

hive-sh4re/src/lib.rs

@@ -373,18 +373,21 @@ pub enum Request {
         file_path: Option<String>,
     },
     /// Loose-ends view. On the agent socket, scoped to the calling agent
-    /// (the `agent` field is ignored — agents can only see their own
-    /// loose ends). On the manager socket, `agent = None` scopes to the
-    /// manager itself, `Some("*")` is hive-wide, `Some("<name>")` is
-    /// that agent's loose ends. See
-    /// `docs/conventions.md::Loose-ends wire shape`.
+    /// unless the agent holds the `query_agent_state` capability, in
+    /// which case `Some("<name>")` targets a specific agent's threads
+    /// (the `"*"` hive-wide value is manager-only). On the manager
+    /// socket, `agent = None` scopes to the manager itself,
+    /// `Some("*")` is hive-wide, `Some("<name>")` is that agent's
+    /// loose ends. See `docs/conventions.md::Loose-ends wire shape`.
     GetLooseEnds {
         #[serde(default, skip_serializing_if = "Option::is_none")]
         agent: Option<String>,
     },
-    /// Count of pending (un-delivered) reminders. On the agent socket
-    /// always scoped to the calling agent. On the manager socket,
-    /// `agent = None` means self, `Some("<name>")` means that agent.
+    /// Count of pending (un-delivered) reminders. On the agent socket,
+    /// scoped to the calling agent unless the agent holds
+    /// `query_agent_state`, in which case `Some("<name>")` targets
+    /// that agent. On the manager socket, `agent = None` means self,
+    /// `Some("<name>")` means that agent.
     /// Used by the harness's per-turn stats sink.
     CountPendingReminders {
         #[serde(default, skip_serializing_if = "Option::is_none")]
@@ -392,15 +395,20 @@ pub enum Request {
     },
     /// Reminder statistics: counts of scheduled, delivered, and pending
     /// reminders over a time window. `since_secs` filters to reminders
-    /// created in the last N seconds (0 = all). On the manager socket
-    /// `agent = None` means self, `Some("<name>")` means that agent.
+    /// created in the last N seconds (0 = all). On the agent socket,
+    /// scoped to the calling agent unless the agent holds
+    /// `query_agent_state`, in which case `Some("<name>")` targets
+    /// that agent. On the manager socket, `agent = None` means self,
+    /// `Some("<name>")` means that agent.
     ReminderRollup {
         /// Only count reminders created in the last N seconds from now.
         /// Pass 0 to include all reminders.
         #[serde(default)]
         since_secs: u64,
         /// Whose reminders to roll up. `None` = the caller's own.
-        /// Manager socket only: `Some("<name>")` = that agent's.
+        /// `Some("<name>")` = that agent's (requires `query_agent_state`
+        /// capability on the agent socket; always available on the manager
+        /// socket).
         #[serde(default, skip_serializing_if = "Option::is_none")]
         agent: Option<String>,
     },
@@ -909,6 +917,14 @@ pub enum Capability {
     /// MCP tool `get_host_journal` is only registered in the harness
     /// when this capability is present.
     ReadHostJournal,
+    /// Agent can query another agent's state via `GetLooseEnds`,
+    /// `CountPendingReminders`, and `ReminderRollup` on the agent
+    /// socket. Without this capability the `agent` field in those
+    /// requests is ignored and results are scoped to the caller.
+    /// The `"*"` hive-wide value is not available on the agent socket
+    /// even with this capability — use the manager socket for swarm-wide
+    /// scans.
+    QueryAgentState,
 }
 
 impl Capability {
@@ -918,6 +934,7 @@ impl Capability {
         match self {
             Self::ManageRootAgent => "manage_root_agent",
             Self::ReadHostJournal => "read_host_journal",
+            Self::QueryAgentState => "query_agent_state",
         }
     }
 }