feat(provider): recover a leaked tool call instead of cutting the turn

[Kiraprint]

What this does

A model served by an endpoint that does not translate its private tool-calling syntax writes the call as visible text — angle brackets, bars, a tool name, a run of JSON. MachineryLeak already convicts that reply, and the harness throws it away: drop the turn, ask once more, reroute the lane, and on a single-model deployment that is the end of the work.

The complaint in #1706 is that this is treated purely as a failure. But the markup is very often a perfectly well-formed tool call the endpoint simply failed to parse. So machineryCut now tries to read the call back out before it cuts.

A reply whose markup holds a call that

1. names a tool the request actually advertised,
2. carries arguments that parse as a JSON object, and
3. is the reply, rather than a quotation inside it,

has that call put on the response and the turn goes on to dispatch it — indistinguishable from a reply that arrived parsed, at every layer below. That is why no lane, retry or accounting is threaded through: the recovery returns nil and the existing epilogue reads an ordinary answered turn. Only a leak that cannot be read that way is still cut, exactly as before.

The refusals are the interesting half

Each is load-bearing, and each is pinned by a test:

• a name the request did not advertise is prose about a call, not a call. A reply smuggling a second, unoffered tool beside a real one is refused outright — this is the one that keeps recovery from becoming an escalation path.
• arguments that do not parse are refused rather than guessed at, with one deliberate exception: a named parameter whose value arrives unencoded (ls, 17, false) is kept as text, because that is what the tool is owed.
• a long tail of prose after the markup is somebody describing tool calls — the one answer a recovery must never destroy.

The measurement that made rule 3 real

An earlier draft of this change assumed the guard around recovery was enough: that a reply merely quoting an invocation is not symbol-dense enough for MachineryLeak to convict. It is not — the markup itself carries the density, and a test caught the assumption.

What separates the two shapes is proportion:

reply	prose outside the markup
captured leak 1	0.25
captured leak 2	0.29
captured leak 3	0.41
a reply quoting an invocation	0.57
a longer reply quoting an invocation	0.64

The bound sits between the groups and nearer the leaks, deliberately: a false refusal falls back to the cut, which is exactly what happened before this change, while a false acceptance dispatches a call nobody made. The measured ratios are asserted in TestTheProseCeilingSeparatesCapturedLeaksFromQuotations, so anyone moving the bound has to move the corpus with it.

Testing

testdata/machineryrecover_dsml.json holds six replies this harness actually threw away in production — three leaks, three post-rejection degenerations — rather than hand-written samples. The narration half matters as much as the leak half: both spell bash in symbols, and the difference is proportion, so a corpus of only leaks would not have found the failure mode.

Call ids are derived from name and arguments rather than random, so a repair repeated over an unchanged reply leaves the prompt prefix byte-identical and the cache still hits.

go build ./..., go vet ./internal/provider/, and the full internal/provider suite pass. A mutation check (removing the unadvertised-name refusal) fails exactly the two tests that claim to cover it.

Measured effect

On one deployment against one model, the leaks stopped killing turns within a day. Before, they were the difference between a task completing and the turn ending in "the reply was the model's own internal markup instead of an answer and was cut".

Notes for review

• The reason codes (ok, no_text, no_tags, fenced, unadvertised, bad_arguments, shape, prose) are part of the contract and are documented as such, so a blind spot stays visible rather than silent.
• recoverProseCeiling is the one number a future change might want to tune. The evidence for moving it is in the table above.
• Nothing outside internal/provider changes behaviour: the manual entry for this failure plane is updated to say the call is read back out and dispatched, and to say what will not be run.

Refs #1706

[CLAassistant]

All committers have signed the CLA.

[santoshkumarradha]

Hey, thanks for the PR. Could you sign the CLA when you get a chance so we can review it?

[ZeroPoint95]

@Kiraprint, the production examples make a credible case for investigating malformed tool output. The first question, though, is whether this recovery approach can reliably distinguish execution intent from quoted examples. The current heuristic doesn’t establish that, so I don’t think we should merge this version.

I reproduced five issues:

1. Quoted examples become executable calls. “Example only; do not run” and inline-backticked examples both return real bash calls. Adjusting the prose threshold won’t establish intent; recovery needs a conservative contract that excludes ambiguous content.
2. Truncated commands are accepted. Missing parameter and invocation closing tags become complete JSON arguments, bypassing the existing protection against repairing severed commands. Please require complete structure and cover truncation explicitly.
3. Argument contents and types change. Recovery folds fullwidth characters, removes literal <tool_calls> text from values, and turns an explicitly string-typed “false” into a boolean. Argument contents and explicit string semantics need to survive unchanged.
4. Recovered markup remains visible during streaming. Clearing final response content doesn’t retract events already emitted to the UI. This needs coverage through the streaming observer path.
5. Identical invocations receive duplicate call IDs. A session-level probe pairs only one of their two results. IDs need to distinguish separate occurrences, with a regression covering result pairing.
   These were reproduced using fake HTTP/SSE responses, without executing recovered commands or making live model calls. Builds, vet, laws and manual checks passed; the provider allocation-test failure also reproduces on the base.
   Before revising individual parsing cases, I’d like us to agree on what evidence makes a malformed response safe to recover as an executable call. Complete, unambiguous envelopes or a provider-side correction look like safer directions