Preserve what a tool already produced across the execution boundary (unifies #282, #299, #300)

[AshrafAhmed9]

Summary

#282, #299, and #300 look like three separate asks for more granular errors, but they're the same underlying gap: the execution boundary between a tool's execute() and the caller (executeTool()) discards information the tool already produced, and replaces it with a generic UnknownError. The fix isn't three different error codes, it's one change: preserve what the tool actually knows before flattening it into a failure.

The three cases

• No structured way to signal a tool's refusal, distinct from success or a schema-validation error #282: a tool deliberately declines a well-formed, schema-valid call (a permission boundary, a business rule). The rejection reason it threw with is discarded; the caller gets UnknownError and can't tell "retry differently" from "ask a human."
• Let a tool deliver a final result on caller abort #299: on caller abort, a tool may already have a settled value worth returning (an { applied, remaining }-shaped partial result, say). That value exists, and is thrown away anyway.
• Clarify that unregistration must not fail an in-flight execution #300: a tool finishes executing, including its side effects, but happens to unregister itself in the process. The caller sees UnknownError even though the execution completed and the effects are real and on screen.

In all three, the tool did its job (declined on purpose, finished with a partial result, finished with a full result) and the boundary reports a fault regardless. The spec's own completion steps flag this same gap four separate times with the identical note: Issue: Support more granular errors than "UnknownError", once per failure case, never generalized.

Why one fix instead of three

Treating these as independent granularity requests means the group has to agree on three separate vocabularies (refusal codes, abort-result shapes, unregistration semantics), and every future case, timeout, network loss inside a tool, anything else a tool might reasonably want to report, becomes a fourth ad hoc carve-out. A single rule, whatever value or reason the tool actually produced before the boundary is reached should reach the caller, not be replaced, closes all three at once and doesn't need a new special case for the next one.

What this doesn't propose

Not a specific envelope shape. Two independent implementations (see below) already converged on roughly the same rough structure (an outcome + a reason + whether retrying makes sense) without knowing about each other, which suggests real convergence pressure, but picking one shape and standardizing it is a separate, harder discussion than just agreeing the information shouldn't be thrown away in the first place. This issue is scoped to the narrower claim: whatever the tool has when it fulfills, rejects, or gets cut off should be preserved and reach the caller in some form, structured or not. What callers are guaranteed to receive can be a follow-up.

Real-world motivation

Two unrelated implementations hit this from different angles before finding each other in #282:

• Consequence (built for the WebMCP Challenge): fields on a form declare who's allowed to fill them. An agent calling answer_question on a human_only field needs to decline clearly, distinct from a validation failure, and today that refusal has to be encoded as a success-shaped text response, because throwing loses the reason at the boundary.
• Redline (github.com/minjikim89/redline, docs/pattern.md): a review tool built on WebMCP, independently landed on returning { ok, error: { code, problems, retrySafe } } as an ordinary result rather than throwing, for the same reason, a refusal isn't a fault, and the caller needs to know whether retrying is meaningful.

Neither of us knew the other existed until this thread. That's the strongest evidence this is a recurring need rather than either app's idiosyncrasy.

Open questions for the group

• Does this belong in the imperative execution algorithm (preserve the rejection reason r instead of discarding it) as a self-contained fix, or does it need a shape/type discussion first?
• Is a completed-but-unregistered execution (Clarify that unregistration must not fail an in-flight execution #300) actually the same code path as a deliberate rejection (No structured way to signal a tool's refusal, distinct from success or a schema-validation error #282), or does it need separate handling since nothing was thrown at all?
• Should the spec guarantee delivery of some value/reason, leaving its shape to authors, or is an untyped any payload too little to build reliable caller behavior on?

Happy to help narrow this further or split it into a concrete PR against the completion steps once there's rough agreement on direction.

[minjikim89]

Thank you for writing this up, @AshrafAhmed9, and for scoping it to the narrow claim rather than to an envelope shape. That seems like the right order, and it keeps the disagreement surface small.

On your second open question, whether a completed-but-unregistered execution is the same code path as a deliberate rejection, I think the answer is no, and #300 is worth treating separately for a reason that helps rather than complicates the proposal.

In #300 nothing is thrown. The tool fulfils, its side effects are already on screen, and the caller is still rejected. The completion steps explain why: they begin by checking the pending tool executions map and returning early if the entry is gone.

1. If |targetDocument|'s ... [=traversable navigable/pending tool executions map=][|uuid|] does not [=map/exist=], then return.

Self-unregistration removes that entry before the tool's own resolution arrives, so the success branch is never reached. The spec's own note describes exactly this as a race between cancellation and tool promise resolution. The rejection the caller sees comes from the cancellation path, not from anything the tool did.

So the three cases share a symptom and split into two mechanisms:

• No structured way to signal a tool's refusal, distinct from success or a schema-validation error #282 and Let a tool deliver a final result on caller abort #299 are about a value that reaches the boundary and is discarded there. Preserving the rejection reason, or the settled value, fixes both.
• Clarify that unregistration must not fail an in-flight execution #300 is about a value that never reaches the boundary, because the execution record was removed first. Preserving reasons would not help it; what it needs is for the removal not to orphan an execution that has already completed, which is close to what Preserve in-flight executions after unregistration #248 established and Clarify that unregistration must not fail an in-flight execution #300 asks to state explicitly.

I do not think that weakens the unification. "Do not discard what the tool produced" still covers all three as a principle, and naming the two mechanisms underneath may make the processing-model change easier to write, since one is an edit to the failure branch and the other is an ordering question about when the entry may be removed.

Separately, and with thanks to @mysticalseeker24's measurements on #299: for the abort case there is a precondition below the preservation question. On Chrome 152 execute receives no options argument, so a tool cannot observe the caller's abort at all. Preserving a settled value presumes a tool that noticed in time to produce one. That may be worth a line in the proposal so the dependency is visible.

Happy to help with the completion-steps wording if it gets that far.

[mlmrx]

Thanks for the tag. I re-read current main and merged #248. One correction may help keep the eventual changes scoped: these are three related product symptoms, but not one execution-boundary mechanism in the current draft.

• No structured way to signal a tool's refusal, distinct from success or a schema-validation error #282 is the direct information-loss case. The imperative rejection branch only optionally reports r to the console, then calls the completion steps with null/false; the caller consequently gets UnknownError. Preserving or standardizing a rejection outcome would change that branch and the failure completion.
• Let a tool deliver a final result on caller abort #299 is an abort-settlement race. The current draft does pass a ToolExecuteCallbackOptions.signal to execute; caller abort immediately rejects the executeTool() promise and starts cancellation, while a later tool fulfillment/rejection returns once its pending entry is gone. See the callback invocation, caller abort steps, and race note. Chrome 152 invoking execute with one argument is therefore implementation lag against the current draft. Delivering a final value after caller abort requires choosing which settlement wins; it is more than retaining an already-returned value.
• Clarify that unregistration must not fail an in-flight execution #300 is already normatively covered by Preserve in-flight executions after unregistration #248. The current unregister algorithm removes only the tool-map entry; it does not remove either pending-execution entry. A self-unregistering tool that has begun should still reach completion. The Chrome 152 result looks like a conformance bug. A targeted WPT and perhaps clarifying prose would be useful, but the current spec should not model self-unregistration as deleting the pending execution.

So I think #308 can retain the unifying principle—do not misreport work the tool performed—while splitting the technical work into #282 outcome transport, #299 cancellation/settlement semantics, and #300 conformance coverage. I would avoid saying one preservation rule closes all three.

[minjikim89]

Hi @mlmrx, thank you for reading the algorithms properly rather than taking my summary at its word. You are right on both counts, and I am glad to withdraw the mechanism I gave for #300 above. The unregister algorithm removes only the tool map entry, so a self-unregistering tool that has begun should still reach completion. Chromium landed exactly that in CL 8224887, and I have verified on Chrome 153 that a tool which aborts its own registration signal mid-execute now resolves normally. The same goes for #299: the draft already passes a signal to execute, Chromium threads it in CL 8025300, and on 153 execute receives the options with a signal, and a loop that checks it stops on caller abort. So what I wrote about a tool being unable to observe the abort described Chrome 152 and not the spec. I have corrected both issue bodies.

Your split is the one I would keep: #282 transport, #299 settlement, #300 conformance, with the principle kept as a principle. Happy to help with wording on any of the three if it gets that far.