Preserve MCP tool error outcomes

[xeophon]

Overview

Preserves MCP tool-declared outcome semantics across harness execution, typed messages, traces, replay, and provider conversion.

This PR is stacked on #2134 and adds structured tool-error transport on top of its shared null/bash lifecycle and replay-safety foundation.

Details

MCP CallToolResult contains both model-visible content and an isError outcome. The shared MCP client now returns both values, and the harness program carries the outcome into ToolMessage.is_error.

The typed outcome participates in graph identity and trace serialization, so success and failure results with identical content remain distinguishable after persistence and resume.

For chat-compatible providers, the localhost harness handoff uses a private marker that is removed before the provider request while adding a readable failure label to the model-visible content. Anthropic-native tool_result.is_error maps directly into the same typed representation.

---

Note

Medium Risk
message_hash now differs for error vs success tool messages, which can change graph dedup for existing traces; provider-facing tool content also gains a failure prefix on chat wire output.

Overview
Adds ToolMessage.is_error so tool failures are typed end-to-end instead of living only in message text.

MCP harness: call_mcp now returns MCP isError; tool messages can carry a private _vf_is_error marker, and chat requests use extra_body.messages so that marker survives the localhost interception path.

Wire / providers: Chat serialization prefixes model-visible content with Tool execution failed: when not using internal mode; harness handoff writes initial messages with include_internal=True. Anthropic tool_result.is_error maps into the same field. apply_overrides re-normalizes messages that still carry the internal marker before the upstream request.

Traces: message_hash for tool nodes includes error vs success, so identical content from a failed vs successful tool call stays distinct after persistence and resume.

^{Reviewed by Cursor Bugbot for commit daab68f. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Preserve MCP tool error outcomes across harness, transcript, and retry logic

• Adds is_error to ToolMessage in types.py and propagates it through Anthropic and chat dialect parsing/serialization, including a _vf_is_error internal key and a human-visible Tool execution failed: prefix on wire output.
• Introduces MCPTransportError and MCPDeliveryUnknownError in errors.py; the harness raises these instead of a generic HarnessError when the program emits a VF_MCP_ERROR= JSON marker.
• Consolidates the null and bash harness programs into a single minimal/program.py with a --bash flag; both harnesses now write initial messages with include_internal=True to preserve error markers.
• mcp_session in the minimal program classifies MCP failures as transient/non-transient and replay-safe/unsafe, and with_retry narrows retries to replay-safe transport failures only.
• Episodes containing MCPDeliveryUnknownError are blocked from retry in retries.py unless explicitly opted in via retry config.
• Risk: message_hash in graph.py now differs between error and success tool outcomes, which may invalidate cached hashes for existing tool messages.

📊 Macroscope summarized daab68f. 13 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces behavioral changes to tool error handling with a new field on a core type. An unresolved review comment from the file's primary author questions the fundamental design approach, which should be resolved before merging.

No code changes detected at daab68f. Prior analysis still applies.

^{You can customize Macroscope's approvability policy. Learn more.}

[mikasenghaas]

why do we need this departure from standard api? can we not just put the error in the content and call it a day?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want reviews to match your repository better? Bugbot Learning can learn team-specific rules from PR activity. A team admin can enable Learning in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 05ea449. Configure here.}

[mikasenghaas]

do we need this only to prefix with TOOL_ERROR_PREFIX? can we not just let the error type bubble up as is. i think its going to be clear enough that the tool call failed. this is also what we do in e.g. rlm harness. e.g. my terminal is also not prefixing every error with Command failed:\n

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.