feat: add canonical tool execution results

Signed-off-by: Bryan Bednarski <bbednarski@nvidia.com>

Author: bbednarski9

.agents/skills/add-binding-feature/SKILL.md

@@ -87,6 +87,9 @@ Lock these before implementing:
 - Does the new API need manual lifecycle and managed execute variants, or only
   one of them?
 - Does the new behavior change event fields, metadata, or scope expectations?
+- If tool execution is affected, does every callback, continuation, managed
+  return, and manual end surface use the canonical `ToolExecutionResult`
+  contract and preserve its opaque annotation?
 - Are docs/examples required because the intended usage changed?
 
 ## Key References

.agents/skills/add-middleware/SKILL.md

@@ -50,6 +50,13 @@ Refer to `docs/about-nemo-relay/concepts/middleware.mdx` for the full diagrams.
   specialized tool or LLM sanitizer (when applicable) -> mark or scope event
   sanitizer -> subscriber and exporter dispatch
 
+Tool execution callbacks and each execution-intercept `next` continuation
+return the canonical `ToolExecutionResult { result, annotation }`. A forwarding
+intercept must preserve both fields in `ToolExecutionInterceptOutcome`; Relay
+retains `pending_marks` separately. Tool sanitize-response guardrails receive
+only `result`. Scope-end event sanitizers govern the annotation after Relay
+projects it to `category_profile.tool_result_annotation`.
+
 ## Core Steps
 
 1. Define or reuse the callback type alias in
@@ -96,6 +103,8 @@ Follow the `add-binding-feature` skill for the cross-binding implementation chec
 - [ ] Callback failure policy, including fail-open behavior when required
 - [ ] Scope-local registration, inheritance, and cleanup on pop
 - [ ] Event payload semantics after middleware mutation
+- [ ] Tool execution result and annotation preservation, replacement, and
+      removal when the middleware touches tool execution
 - [ ] Mark and scope event field semantics, including immutable identity fields
 - [ ] Parity coverage in every affected binding
 

.agents/skills/contribute-docs/SKILL.md

@@ -28,10 +28,10 @@ Use this skill for docs-only or example-heavy changes.
   only point at namespaced helper paths when documenting internal maintenance
   work
 - When detailed dynamic plugin guides exist, keep Rust native plugin examples,
-  Python worker plugin examples, and `grpc-v1` protocol details on separate
+  Python worker plugin examples, and `grpc-v2` protocol details on separate
   pages.
-- Dynamic plugin manifests in docs/examples should use
-  `compat.relay = ">=0.5,<1.0"` unless deliberately narrower.
+- Dynamic plugin manifests that use native API 2 or `grpc-v2` should use
+  `compat.relay = ">=0.8.0,<1.0"` unless deliberately narrower.
 - In MDX files, top-of-file comments must use JSX comment delimiters:
   `{/*` to open and `*/}` to close. Do not use HTML comments for MDX SPDX
   headers.

.agents/skills/contribute-integration/SKILL.md

@@ -28,6 +28,9 @@ as LangChain, LangGraph, Deep Agents, or OpenClaw through its public APIs.
 
 - [ ] Integration pattern follows `docs/integrate-into-frameworks/adding-scopes.mdx`
 - [ ] Integration uses public framework or plugin APIs
+- [ ] Managed tool adapters return `ToolExecutionResult` to Relay and unwrap
+      `.result` only at the framework boundary; opaque annotations are
+      preserved through forwarding execution intercepts
 - [ ] Relevant integration tests or smoke path pass
 - [ ] Docs updated if activation or usage changed
 

.agents/skills/maintain-dynamic-plugins/SKILL.md

@@ -20,7 +20,7 @@ Use this skill for `plugin.kind = "rust_dynamic"`, `plugin.kind = "worker"`,
 ## Rules
 
 - Keep the stable boundary explicit: native plugins cross a C ABI; worker
-  plugins cross `grpc-v1`.
+  plugins cross `grpc-v2`.
 - Do not pass Rust runtime types, trait objects, futures, or allocator-owned
   strings across the native dynamic-library boundary.
 - Typed native middleware futures run on the SDK-owned Tokio executor. Keep
@@ -30,9 +30,9 @@ Use this skill for `plugin.kind = "rust_dynamic"`, `plugin.kind = "worker"`,
 - Keep `relay-plugin.toml` dynamic records separate from generic runtime
   components. Enabled dynamic records may synthesize internal component specs;
   disabled records stay inspectable but unloaded.
-- Treat plugin Relay compatibility as normal SemVer. Typed async native plugin
-  examples require `>=0.8.0,<1.0`; other examples use `>=0.5,<1.0` unless a
-  plugin intentionally declares a narrower range.
+- Treat plugin Relay compatibility as normal SemVer. Native API 2 and `grpc-v2`
+  examples require `>=0.8.0,<1.0` unless a plugin intentionally declares a
+  narrower range.
 - Do not add tests under `src`; Rust tests belong in crate `tests/` trees and
   Python SDK tests belong under `python/tests`.
 - Native and worker plugins are trusted extensions. Document that native plugins
@@ -55,7 +55,7 @@ Use this skill for `plugin.kind = "rust_dynamic"`, `plugin.kind = "worker"`,
 - [ ] Top-level `doctor` reports resolved dynamic plugin and host configuration
       status.
 - [ ] When detailed dynamic plugin guides exist, they keep Rust native, Python
-      worker, and `grpc-v1` protocol details on separate pages.
+      worker, and `grpc-v2` protocol details on separate pages.
 - [ ] `justfile`, Codecov, and CI package/test workflows include new plugin
       crates and packages.
 

.agents/skills/maintain-observability/SKILL.md

@@ -50,6 +50,11 @@ OpenTelemetry projections.
 - [ ] Does Relay derive compliant trace and span IDs consistently across typed
   OpenTelemetry endpoints while preserving lifecycle parentage?
 - [ ] Are mark events, start/end events, and orphan cases still handled correctly?
+- [ ] Does a sanitized tool result annotation remain opaque under
+      `category_profile.tool_result_annotation`, ATIF observation-result
+      `extra.tool_result_annotation`, and the single
+      `nemo_relay.tool.result.annotation` attribute in `full` and
+      `openinference`, while `gen_ai` omits it?
 - [ ] Do examples and docs use each exporter's documented flush/deregister
   order before shutdown?
 - [ ] Are span or trajectory fields still derived from the intended event data?

crates/adaptive/tests/integration/runtime_integration_tests.rs

@@ -618,7 +618,7 @@ async fn test_adaptive_plugin_registers_and_passes_calls_through() {
     .unwrap();
     assert_eq!(llm_result, json!({"response": "ok"}));
 
-    let tool_func: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args) }));
+    let tool_func: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args.into()) }));
     let tool_result = tool_call_execute(
         nemo_relay::api::tool::ToolCallExecuteParams::builder()
             .name("search")
@@ -628,7 +628,7 @@ async fn test_adaptive_plugin_registers_and_passes_calls_through() {
     )
     .await
     .unwrap();
-    assert_eq!(tool_result, json!({"query": "test"}));
+    assert_eq!(tool_result.result, json!({"query": "test"}));
 
     clear_plugin_configuration().unwrap();
 }
@@ -822,7 +822,7 @@ async fn test_top_level_plugin_registers_request_and_execution_intercepts() {
     .unwrap();
     assert_eq!(request.request.headers.get("x-plugin"), Some(&json!("set")));
 
-    let tool_func: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args) }));
+    let tool_func: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args.into()) }));
     let tool_result = tool_call_execute(
         nemo_relay::api::tool::ToolCallExecuteParams::builder()
             .name("search")
@@ -832,7 +832,7 @@ async fn test_top_level_plugin_registers_request_and_execution_intercepts() {
     )
     .await
     .unwrap();
-    assert_eq!(tool_result["x-tool-plugin"], json!(true));
+    assert_eq!(tool_result.result["x-tool-plugin"], json!(true));
 
     let llm_func: LlmExecutionNextFn =
         Arc::new(|_req: LlmRequest| Box::pin(async move { Ok(json!({"response": "ok"})) }));

crates/adaptive/tests/unit/intercepts_tests.rs

@@ -99,7 +99,7 @@ async fn test_tool_intercept_calls_next() {
     let intercept = create_tool_execution_intercept(hot_cache);
 
     let next: ToolExecutionNextFn =
-        Arc::new(|_args| Box::pin(async move { Ok(json!({"result": "ok"})) }));
+        Arc::new(|_args| Box::pin(async move { Ok(json!({"result": "ok"}).into()) }));
 
     let result = intercept("test", json!({"input": 1}), next).await;
     assert!(result.is_ok());
@@ -121,7 +121,7 @@ async fn test_tool_intercept_with_populated_cache() {
     let intercept = create_tool_execution_intercept(hot_cache);
 
     let next: ToolExecutionNextFn =
-        Arc::new(|_args| Box::pin(async move { Ok(json!({"from_next": true})) }));
+        Arc::new(|_args| Box::pin(async move { Ok(json!({"from_next": true}).into()) }));
 
     // Should not panic and should return next's result
     let result = intercept("test", json!({"tool_input": "data"}), next).await;
@@ -143,7 +143,7 @@ async fn test_tool_intercept_passes_args_to_next() {
     let intercept = create_tool_execution_intercept(hot_cache);
 
     // next captures and returns the args it received, proving pass-through
-    let next: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args) }));
+    let next: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args.into()) }));
 
     let input = json!({"tool_arg": "value", "count": 42});
     let result = intercept("test", input.clone(), next).await;
@@ -317,7 +317,7 @@ async fn test_schedule_mode_intercept_waits_for_primer_before_running_follower()
                         "follower should not call next until the primer has released the cohort"
                     );
                 }
-                Ok(args)
+                Ok(args.into())
             })
         })
     };

crates/adaptive/tests/unit/runtime_features_tests.rs

@@ -623,7 +623,7 @@ async fn tool_parallelism_feature_registers_execution_intercept() {
     feature.register(&mut ctx).await.unwrap();
     assert_tool_execution_intercept_registered(&name);
 
-    let next: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args) }));
+    let next: ToolExecutionNextFn = Arc::new(|args| Box::pin(async move { Ok(args.into()) }));
     let result = tool_call_execute(
         nemo_relay::api::tool::ToolCallExecuteParams::builder()
             .name("search")
@@ -633,7 +633,7 @@ async fn tool_parallelism_feature_registers_execution_intercept() {
     )
     .await
     .unwrap();
-    assert_eq!(result["query"], json!("coverage"));
+    assert_eq!(result.result["query"], json!("coverage"));
 
     let mut registrations = ctx.finish();
     rollback_registrations(&mut registrations);

crates/cli/src/sessions/mod.rs

@@ -1249,7 +1249,7 @@ impl Session {
             tool_call_end(
                 ToolCallEndParams::builder()
                     .handle(&handle)
-                    .result(json!({ "status": reason }))
+                    .execution_result(json!({ "status": reason }).into())
                     .metadata(json!({ "status": reason }))
                     .build(),
             )?;
@@ -1570,7 +1570,7 @@ impl Session {
         tool_call_end(
             ToolCallEndParams::builder()
                 .handle(&handle)
-                .result(event.result.clone())
+                .execution_result(event.result.clone().into())
                 .metadata(merge_metadata(
                     event_metadata,
                     json!({ "status": event.status }),