feat: correlate managed tool calls by external ID

[bbednarski9]

Overview

This adds the missing external tool-call correlation ID to managed tool execution across Rust, Python, Node.js, C FFI, and Go. A provider, harness, or transport can now supply one stable ID at the managed execution boundary, and Relay places that ID on the matching tool start and end events across success, callback error, and cancellation.

This is the final runtime gap in the tool-provenance direction described by #446:

• [Enhancement]: Seed isolated scope stacks from external parent context #444 supplies explicit cross-process Relay parent context.
• feat!: add canonical tool execution results #575 supplies the canonical application-visible tool result and annotation contract.
• This PR supplies the external invocation ID at the managed execution boundary and forwards it through supported framework middleware.

The code is independently mergeable on main; complete closure of the broader #446 contract assumes #575 also lands. Relay continues to expose transport-neutral primitives rather than owning MCP transport or adding a protocol-specific proxy.

• I confirm this contribution is my own work, or I have the right to submit it under this project's license.
• I searched existing issues and open pull requests, and this does not duplicate existing work.

Details

• Adds optional tool_call_id / toolCallId support to managed execution in Rust, Python, and Node.js, including typed wrappers.
• Preserves the exact supplied ID on the runtime's provisional start/end lifecycle. General event sanitizers can still redact or remove it from published category_profile data.
• Covers success, callback failure, and cancellation with the same lifecycle UUID and external ID. Omitted IDs remain absent.
• Keeps conditional guardrail rejection before lifecycle creation, so rejected calls still emit no managed tool start/end pair.
• Updates LangChain sync and async middleware to forward ToolCallRequest.tool_call["id"]; the Deep Agents integration inherits the same behavior.
• Preserves the existing C ABI entry point and adds nemo_relay_tool_call_execute_v2(..., tool_call_id, out) instead of changing the legacy signature.
• Makes the existing Go WithToolCallID option apply to ToolCallExecute as well as manual lifecycle calls.
• Documents the transport-neutral mapping for local, MCP-backed, and other remote tools: keep full result data intact, distinguish callback failures from valid error-status results, carry external Relay parent context separately, and leave transport/authentication ownership with the application.

Validation completed:

• cargo test --workspace --all-features --no-fail-fast -- --test-threads=1
• cargo clippy --workspace --all-targets --all-features -- -D warnings
• cargo fmt --all -- --check
• Python: 654 passed
• Python LangChain, LangGraph, and Deep Agents integrations: 66 passed, 2 skipped
• Node.js: 373 passed
• FFI: 90 unit and 82 integration tests passed
• Go: all 10 packages passed
• Changed-files pre-commit suite passed, including Ruff, ty, docs links, FFI header sync, Cargo checks, Go formatting/vet, and Node formatting/docstrings. The unrelated Python worker protobuf hook was skipped because just is unavailable; this PR does not change worker protobufs.
• git diff --check

Where should the reviewer start?

Start with crates/core/src/api/tool.rs and the managed lifecycle regressions in crates/core/tests/integration/middleware_tests.rs. They show the central behavior for success, failure, cancellation, omission, and guardrail rejection.

Then review crates/ffi/src/api/tool_lifecycle.rs with crates/ffi/nemo_relay.h for the additive C ABI decision, and python/nemo_relay/integrations/langchain/middleware.py for framework ID forwarding. The application/protocol responsibility boundary is documented in docs/integrate-into-frameworks/wrap-tool-calls.mdx.

Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

• Closes [Enhancement]: Add MCP and tool ID for tool-call provenance and correlation #446
• Relates to [Enhancement]: Seed isolated scope stacks from external parent context #444
• Relates to feat!: add canonical tool execution results #575
• Relates to [Enhancement]: Add cross-binding MCP client mapping for managed tool execution #742

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 02ef1e44-baac-4bfd-9bf8-c4fc9a05c5dd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Fern docs preview: https://nvidia-preview-pull-request-773.docs.buildwithfern.com/nemo/relay/dev