feat(reborn): Context management — progressive tool disclosure (flag-gated, default off)

crates/ironclaw_agent_loop/src/executor/prompt.rs

@@ -233,12 +233,27 @@ impl<'a> PromptPlanningPipeline<'a> {
         }
 
         let surface = self.visible_surface(surface_filter).await?;
-        let capability_view = LoopModelCapabilityView {
-            visible_capability_ids: surface
+        // The capability view drives call-time authorization (the model-visible
+        // capability filter), which must permit every tool the model can legitimately
+        // invoke this turn — not just the advertised subset. Under progressive tool
+        // disclosure the surface narrows `descriptors` to the advertised set but
+        // carries the full reachable catalog in `callable_capability_ids`; use that
+        // wider set so bridge / forgiving-direct calls to disclosed-but-unadvertised
+        // tools aren't rejected as "outside the model-visible capability view".
+        // Advertising and prompt rendering still use the narrow `descriptors`.
+        // Empty `callable_capability_ids` means no narrowing is in effect, so fall
+        // back to `descriptors` (preserves non-disclosure behavior exactly).
+        let visible_capability_ids = if surface.callable_capability_ids.is_empty() {
+            surface
                 .descriptors
                 .iter()
                 .map(|descriptor| descriptor.capability_id.clone())
-                .collect(),
+                .collect()
+        } else {
+            surface.callable_capability_ids.clone()
+        };
+        let capability_view = LoopModelCapabilityView {
+            visible_capability_ids,
         };
         self.state.surface_version = Some(surface.version.clone());
         if let Some(exit) = self.cancel_boundary().await? {

crates/ironclaw_agent_loop/src/executor/tests/support.rs

@@ -682,6 +682,7 @@ impl ironclaw_turns::run_profile::LoopCapabilityPort for MockHost {
         Ok(VisibleCapabilitySurface {
             version: self.visible_surface_version.clone(),
             descriptors,
+            callable_capability_ids: Vec::new(),
         })
     }
 

crates/ironclaw_agent_loop/src/test_support/mod.rs

@@ -776,6 +776,7 @@ impl ironclaw_turns::run_profile::LoopCapabilityPort for MockAgentLoopDriverHost
     ) -> Result<VisibleCapabilitySurface, AgentLoopHostError> {
         self.record_call(MockHostCall::VisibleCapabilities);
         Ok(VisibleCapabilitySurface {
+            callable_capability_ids: Vec::new(),
             version: surface_version(),
             descriptors: self.visible_capabilities.clone(),
         })

crates/ironclaw_hooks/src/middleware/capability_port.rs

@@ -655,6 +655,7 @@ mod tests {
             _request: VisibleCapabilityRequest,
         ) -> Result<VisibleCapabilitySurface, AgentLoopHostError> {
             Ok(VisibleCapabilitySurface {
+                callable_capability_ids: Vec::new(),
                 version: CapabilitySurfaceVersion::new("v1").expect("ok"),
                 descriptors: vec![CapabilityDescriptorView {
                     capability_id: CapabilityId::new("cap.x").expect("ok"),

crates/ironclaw_hooks/src/middleware/tests/capability_port.rs

@@ -51,6 +51,7 @@ impl LoopCapabilityPort for AlwaysCompletedPort {
         _request: VisibleCapabilityRequest,
     ) -> Result<VisibleCapabilitySurface, AgentLoopHostError> {
         Ok(VisibleCapabilitySurface {
+            callable_capability_ids: Vec::new(),
             version: CapabilitySurfaceVersion::new("v1").expect("ok"),
             descriptors: vec![CapabilityDescriptorView {
                 capability_id: CapabilityId::new("cap.x").expect("ok"),

crates/ironclaw_llm/src/nearai_chat.rs

@@ -585,14 +585,16 @@ impl LlmProvider for NearAiChatProvider {
         };
 
         let (input_tokens, output_tokens) = parse_usage(response.usage.as_ref());
+        let cached_tokens = parse_cached_tokens(response.usage.as_ref());
+        emit_context_shadow_usage(input_tokens, output_tokens, cached_tokens);
 
         Ok(CompletionResponse {
             content,
             finish_reason,
             input_tokens,
             output_tokens,
             reasoning: provider_reasoning,
-            cache_read_input_tokens: 0,
+            cache_read_input_tokens: cached_tokens.unwrap_or(0).min(input_tokens),
             cache_creation_input_tokens: 0,
         })
     }
@@ -696,14 +698,16 @@ impl LlmProvider for NearAiChatProvider {
         };
 
         let (input_tokens, output_tokens) = parse_usage(response.usage.as_ref());
+        let cached_tokens = parse_cached_tokens(response.usage.as_ref());
+        emit_context_shadow_usage(input_tokens, output_tokens, cached_tokens);
 
         Ok(ToolCompletionResponse {
             content,
             tool_calls,
             finish_reason,
             input_tokens,
             output_tokens,
-            cache_read_input_tokens: 0,
+            cache_read_input_tokens: cached_tokens.unwrap_or(0).min(input_tokens),
             cache_creation_input_tokens: 0,
             reasoning: provider_reasoning,
         })
@@ -1143,6 +1147,16 @@ struct ChatCompletionUsage {
     completion_tokens: Option<u64>,
     #[serde(default)]
     total_tokens: Option<u64>,
+    #[serde(default)]
+    prompt_tokens_details: Option<PromptTokensDetails>,
+    #[serde(default)]
+    cached_tokens: Option<u64>,
+}
+
+#[derive(Debug, Deserialize, Default)]
+struct PromptTokensDetails {
+    #[serde(default)]
+    cached_tokens: Option<u64>,
 }
 
 fn saturate_u32(val: u64) -> u32 {
@@ -1165,6 +1179,33 @@ fn emit_reasoning_trace(reasoning: Option<&str>) {
     }
 }
 
+fn emit_context_shadow_usage(
+    prompt_tokens: u32,
+    completion_tokens: u32,
+    cached_tokens: Option<u32>,
+) {
+    const CONTEXT_SHADOW_TARGET: &str = "ironclaw::reborn::context_shadow";
+    let cached_tokens_field = cached_tokens.map(i64::from).unwrap_or(-1);
+    if let Some(cached_tokens) = cached_tokens.filter(|_| prompt_tokens > 0) {
+        tracing::debug!(
+            target: CONTEXT_SHADOW_TARGET,
+            prompt_tokens,
+            completion_tokens,
+            cached_tokens = cached_tokens_field,
+            cache_hit_ratio = cached_tokens as f64 / prompt_tokens as f64,
+            "nearai chat usage shadow measurement"
+        );
+    } else {
+        tracing::debug!(
+            target: CONTEXT_SHADOW_TARGET,
+            prompt_tokens,
+            completion_tokens,
+            cached_tokens = cached_tokens_field,
+            "nearai chat usage shadow measurement"
+        );
+    }
+}
+
 fn parse_usage(usage: Option<&ChatCompletionUsage>) -> (u32, u32) {
     let Some(u) = usage else {
         return (0, 0);
@@ -1181,6 +1222,16 @@ fn parse_usage(usage: Option<&ChatCompletionUsage>) -> (u32, u32) {
     (input, output)
 }
 
+fn parse_cached_tokens(usage: Option<&ChatCompletionUsage>) -> Option<u32> {
+    let usage = usage?;
+    usage
+        .prompt_tokens_details
+        .as_ref()
+        .and_then(|details| details.cached_tokens)
+        .or(usage.cached_tokens)
+        .map(saturate_u32)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2744,6 +2795,8 @@ mod tests {
             prompt_tokens: Some(100),
             completion_tokens: Some(50),
             total_tokens: Some(150),
+            prompt_tokens_details: None,
+            cached_tokens: None,
         };
         assert_eq!(parse_usage(Some(&usage)), (100, 50));
     }
@@ -2759,6 +2812,8 @@ mod tests {
             prompt_tokens: Some(100),
             completion_tokens: None,
             total_tokens: Some(180),
+            prompt_tokens_details: None,
+            cached_tokens: None,
         };
         // output = total - prompt = 80
         assert_eq!(parse_usage(Some(&usage)), (100, 80));
@@ -2770,6 +2825,8 @@ mod tests {
             prompt_tokens: None,
             completion_tokens: None,
             total_tokens: Some(200),
+            prompt_tokens_details: None,
+            cached_tokens: None,
         };
         // input = 0 (no prompt), output = total = 200
         assert_eq!(parse_usage(Some(&usage)), (0, 200));
@@ -2781,6 +2838,8 @@ mod tests {
             prompt_tokens: None,
             completion_tokens: None,
             total_tokens: None,
+            prompt_tokens_details: None,
+            cached_tokens: None,
         };
         assert_eq!(parse_usage(Some(&usage)), (0, 0));
     }
@@ -2935,13 +2994,80 @@ mod tests {
         assert_eq!(usage.total_tokens, Some(500));
     }
 
+    #[test]
+    fn test_usage_deserialize_nested_cached_tokens() {
+        let json = r#"{
+            "prompt_tokens": 100,
+            "completion_tokens": 25,
+            "total_tokens": 125,
+            "prompt_tokens_details": {
+                "cached_tokens": 80
+            }
+        }"#;
+        let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
+        assert_eq!(parse_usage(Some(&usage)), (100, 25));
+        assert_eq!(parse_cached_tokens(Some(&usage)), Some(80));
+    }
+
+    #[test]
+    fn test_usage_deserialize_top_level_cached_tokens() {
+        let json = r#"{
+            "prompt_tokens": 100,
+            "completion_tokens": 25,
+            "total_tokens": 125,
+            "cached_tokens": 40
+        }"#;
+        let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
+        assert_eq!(parse_cached_tokens(Some(&usage)), Some(40));
+    }
+
+    #[test]
+    fn test_usage_deserialize_prefers_nested_cached_tokens() {
+        let json = r#"{
+            "prompt_tokens": 100,
+            "completion_tokens": 25,
+            "total_tokens": 125,
+            "prompt_tokens_details": {
+                "cached_tokens": 80
+            },
+            "cached_tokens": 40
+        }"#;
+        let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
+        assert_eq!(parse_cached_tokens(Some(&usage)), Some(80));
+    }
+
+    #[test]
+    fn test_usage_deserialize_cached_tokens_absent() {
+        let json = r#"{
+            "prompt_tokens": 100,
+            "completion_tokens": 25,
+            "total_tokens": 125
+        }"#;
+        let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
+        assert_eq!(parse_cached_tokens(Some(&usage)), None);
+    }
+
+    #[test]
+    fn test_usage_without_details_still_parses_token_counts() {
+        let json = r#"{
+            "prompt_tokens": 10,
+            "completion_tokens": 5,
+            "total_tokens": 15
+        }"#;
+        let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
+        assert_eq!(parse_usage(Some(&usage)), (10, 5));
+        assert_eq!(parse_cached_tokens(Some(&usage)), None);
+    }
+
     #[test]
     fn test_usage_deserialize_empty_object() {
         let json = "{}";
         let usage: ChatCompletionUsage = serde_json::from_str(json).unwrap();
         assert!(usage.prompt_tokens.is_none());
         assert!(usage.completion_tokens.is_none());
         assert!(usage.total_tokens.is_none());
+        assert!(usage.prompt_tokens_details.is_none());
+        assert!(usage.cached_tokens.is_none());
     }
 
     // -- ChatCompletionToolCall serde roundtrip --------------------------------

crates/ironclaw_loop_support/src/capability_port.rs

@@ -1329,6 +1329,9 @@ impl LoopCapabilityPort for HostRuntimeLoopCapabilityPort {
         Ok(VisibleCapabilitySurface {
             version,
             descriptors,
+            // Empty = "callable == advertised". A disclosure decorator that narrows
+            // the advertised set populates this with the wider reachable catalog.
+            callable_capability_ids: Vec::new(),
         })
     }