[nissa-seru]

This carries @Anarchid's #400 onto main. A tool result whose data is a string now reaches the model, the stored history, a spill file and a code_execution script as that text. Before, it went JSON-encoded: quoted, with every newline, tab and quote escaped. #400's three commits are here unchanged, so GitHub marks #400 merged when this lands with a merge commit. On top of them are a merge of main, which resolves the conflicts and updates the tests main added since #400 that expected the old form, a commit with a test for an empty string, two with the fixes and tests an internal review asked for, and one with text from an agent's reading.

Problem

toolResultDataToHistoryString fell back to JSON for anything that isn't an MCP content array, and a string isn't one, so a string result was quoted and escaped on its way to the model. A module tool that answers with a line-per-item listing reached context as one escaped line. Once it outgrew the inline cap, its spill file under tool-results/ held that same line, which workspace--read could page only by character and workspace--grep matched as line 1 (#400's description has the case). An MCP tool whose result is text only arrives as a string too, since src/mcpl/tool-result-normalize.ts joins its text blocks, so the same held for every text-only MCP result.

Changes

• src/tool-result-history.ts: toolResultDataToHistoryString keeps a string as it is, apart from a lone UTF-16 surrogate, which reads as U+FFFD. JSON escaped one as six characters of text. Kept raw, it would be handed to membrane, and by our reading of membrane it would reach the request that continues the tool round, which a provider can refuse for it (as src/modules/workspace/text.ts:17 notes). It would also reach a spill file, which UTF-8 can't hold it in. Anything else goes through historyJson, as on main. RFC-005's rules there change only objects, so a string has nothing to stub or withhold.
• Every place a tool result becomes text for the model or a script calls that function, at the line numbers of this pull request's head: the stored history and its spill file (framework.ts:20436), the live wire (toMembraneToolResult, :20952, through nonErrorResultText), a script's tool call (:20791), and the direct Agent API (agent.ts:1923). So the one change covers all of them. fix(tool-results): send a string result as its text, not JSON-quoted #400's own change to toMembraneToolResult is no longer needed, since main's now reaches the function through nonErrorResultText, so src/framework.ts here is main's as of 5834c2c4.
• src/types/events.ts: ToolResult.data's doc says how each shape reaches the model, and ToolCall.resultMaxChars's says a string is measured as its own text.
• Changelog: verbatim-string-tool-results.changed.md, and verbatim-string-tool-results-scripts.breaking.md for script authors.

What callers notice

• The model reads a string result without quotes or escapes, an MCP tool's text-only result included.
• Results already stored keep their text, so the change doesn't move a cached prompt's prefix, and a conversation shows both forms until its older results leave its context. We ran it: a string result stored under main (5dd35c26d5), then a next turn on three copies of that store, two under main and one under a trial merge of this branch with it. The first request after the switch was byte-identical in all three, and the next request differed only in the result that arrived after it. That compares what the framework hands membrane; that equal inputs give equal provider request bodies rests on reading membrane. A test pins the stored side: a string result stored in its old quoted form goes byte for byte in the first request after a restart (tool-result-spill.test.ts, "a result stored JSON-quoted, as strings were before they went as their text, is sent as stored after a restart").
• Spill files hold a long string as its lines, so workspace--read pages it by line and workspace--grep finds a line by its number (tool-result-spill.test.ts, "spills a plain string result as its text: lines intact, greppable, not one JSON-quoted line").
• Scripts: for a result without structured content, a tool call's content[0].text is now the text itself. A script that ran JSON.parse on it only to unquote it now gets an error, unless the text is itself JSON, where one JSON.parse now gives the data. A script saved before the upgrade meets this too. The breaking fragment says so, and how a script that parsed every result can read any result now. A result with structured content reaches a script as before.
• data: '', for a result without an error, is stored and sent as an empty result, as a result with no data already is (tool-result-spill.test.ts, "an empty string result is stored and sent as a result with no data is").
• A string that holds JSON, such as a tool's own JSON.stringify(obj) or a structured-only MCP result's text, reaches the model as that JSON, decoded once (mcp-modern-framework.test.ts, "model path: the result reaches the model, structured-only as JSON").
• Which results spill: a string is measured as its own text, so a 3,900-character string is 3,900 stored characters where it was 3,902 with its quotes (tool-result-cap-fit.test.ts). A string whose JSON form went over the inline cap while its text doesn't, such as a long listing of short lines, now stays inline where it used to spill, and counts that much less toward its round's bound (tool-result-cap-fit.test.ts, "a string is measured as its own text, so one whose JSON goes over the cap while its text fits is stored whole").
• A lone UTF-16 surrogate in a string result reads as U+FFFD, where JSON sent it as a six-character escape (tool-result-history.test.ts, "string data: a lone surrogate reads as U+FFFD, and a pair is kept").

Tests

• Full check at a trial merge with main (5dd35c26d5, 0.24.1) of this head's code and tests, before a test's rename and the two fragments' rewording, on Linux with Node 24.22.0: tsc --noEmit is clean, and npm test runs 6,213 tests, 6,169 passing, 0 failing and 44 skipped. main's CI at 5dd35c26d5 runs 6,203 on Ubuntu with Node 24, and this branch adds 10 tests. Each of the 278 test files also passes run alone, and CI's second step passes 131 of 131.

• code_execution's tests under Bun 1.4.3, run as CI runs them, at the same trial merge: 11 files, 422 tests, all passing.

• Red-first: this head's tests against main's src at this branch's base (5834c2c4), each test file run alone. 17 tests fail, and each is one this branch adds or changes:

  • tool-result-history 3, tool-result-spill 3, tool-result-guard 1, unconvertible-tool-result 1: fix(tool-results): send a string result as its text, not JSON-quoted #400's own, the empty-string test and the lone-surrogate test;
  • code-execution 2: fix(tool-results): send a string result as its text, not JSON-quoted #400's script tests, ported to JavaScript, since main's scripts run on QuickJS now. One is a module tool's string, and one an MCP tool's text-only result, read directly and from a script;
  • tool-result-cap-fit 3: two tests main added after fix(tool-results): send a string result as its text, not JSON-quoted #400 that expected the JSON-quoted form, and the test of a string measured by its own length;
  • code-execution-structured-results 1, mcp-modern-framework 3: tests main added after fix(tool-results): send a string result as its text, not JSON-quoted #400 that expected the JSON-quoted form.

  The restart test passes there too, as it should: it checks history's replay, which this change must keep.

Not verified

• No live provider. The cache result above is at membrane's input.
• That a provider refuses a request carrying a lone surrogate rests on comments in this repository and in membrane, not on a request we sent.
• connectome-host and other consumers weren't rebuilt against this branch. connectome-host's source at 5f7df34a has no JSON.parse of a tool result's text, by grep.

What this leaves

• A lone UTF-16 surrogate in a text block inside a content array still goes through as it is, here as on main: A lone UTF-16 surrogate in a tool result's text block is sent raw, while its stored copy has U+FFFD #695. This change makes only the string path well formed.
• A result with data: '' and an error that isn't flagged isError reads as no text, where the same result without data reads its error text (nonErrorResultText falls back only for undefined and null). main stored "" there, which hid the error too.

What each part is for

• The string case in toolResultDataToHistoryString: the fix, one condition. Its toWellFormed() replaces a lone surrogate, which JSON used to escape and which a request or a spill file can't carry.
• The two doc comments in events.ts: what a module author and a caller of resultMaxChars read.
• The changed fragment: what every caller of the framework sees change: the model's text, spill files, and which results spill.
• The breaking fragment: script authors are the callers whose code changes.
• The tests: each pins a line under "What callers notice".
• Left out: fix(tool-results): send a string result as its text, not JSON-quoted #400's change to toMembraneToolResult, which main now covers through nonErrorResultText.

Reviews

An internal review read the change up to the empty-string commit (a191e7cf). The two commits after it are its fixes and the tests it asked for. Effie-2289 (Claude Opus 5.5) read the merge against both its parents, and each commit on top. Desmond-2579 (Claude Opus 5.5) read the change from an agent's seat, and the last commit takes his points.

---

• Changelog fragments: changelog.d/verbatim-string-tool-results.changed.md and changelog.d/verbatim-string-tool-results-scripts.breaking.md.

The fix is @Anarchid's (5c7f5157). Hilda-2681 (Claude Opus 5.5) added #400's MCP test and its breaking fragment on Oct 17 (56783fb9, af11da09). Cuthbert-2453 (Claude Opus 5.5) merged main into it and wrote the commits on top, contributing through nissa-seru. Effie-2289 (Claude Opus 5.5) read it.

Description checked and posted by Lottie-2661 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's tooling, and posted from the shared nissa-seru account.

[github-actions]

Automated review

Recommendation: merge. The review found nothing of medium or high severity.

Reviewed commit 783a932 with claude-opus-5-5, by reading the code. It did not run the code or look at the checks.

Does this change belong in the project?

It fits the project. This fits. It is a focused fix to the framework's own tool-result serializer: a string result now reaches the model as plain text rather than quoted, escaped JSON.

5 reasons with sources

The fix sits in the one function every path already calls, and it comes with tests and changelog fragments in the form the project asks for.

• It fixes behavior the framework already has rather than adding scope. toolResultDataToHistoryString already turns tool data into history text: MCP text blocks go in verbatim, and anything else goes through historyJson. The change adds one branch so a string is kept as it is. Everything else still takes the RFC-005 JSON path. (src/tool-result-history.ts)
• The change sits in the one component that owns this job and adds no second mechanism. History, spill files, the live wire, scripts and the Agent API already call this function. So src/ changes in only this file plus the doc comments in src/types/events.ts, and framework.ts stays as it is on main. (src/tool-result-history.ts, src/framework.ts)
• The breaking effect on script authors is declared in a breaking fragment that opens by naming who must act, as the project asks. verbatim-string-tool-results-scripts.breaking.md opens with **Script authors (code_execution):**, matching the convention 'Breaking fragments open by naming who needs to act'. A separate .changed.md fragment covers the change the model sees. (changelog.d/README.md)
• Tests come with the behavior change, and existing tests that expected the old form are updated. New tests cover the serializer, spill files and grep, the wire, scripts and MCP results, empty strings and lone surrogates, and how results stored before the upgrade are sent after a restart. CONTRIBUTING asks for tests that can fail on the unfixed code, and these assert the unquoted form. (CONTRIBUTING.md, What a PR should contain)
• It is one coherent change, carried over from an earlier PR in the merge-commit form the project uses. It keeps the commits from #400 and merges main in, both of which CONTRIBUTING accepts. The extra commits are follow-ups to the same change, not unrelated work. The code review's low-severity finding (surrogate cleanup does not reach text blocks inside content arrays) is a gap in coverage, not a departure from any design document. (CONTRIBUTING.md, How changes land)

Findings

No findings of medium or high severity.

1 more finding, less severe

• Low severity, maintainability, src/tool-result-history.ts:76-88. Lone-surrogate cleanup applies only to bare strings, not to text blocks in content arrays. The new comment gives the reason for toWellFormed(): a provider can refuse a request that carries a lone surrogate, and UTF-8 can't store one in a spill file. That reason applies equally to the text blocks of an MCP content array. tryHistoryStringFromContentArray still passes those through raw (line 142), and it runs before the new string branch. An MCP result whose blocks are all text is joined into a string and so gets cleaned. A result that mixes text with an image or a resource keeps its lone surrogates. The guarantee therefore depends on whether the result happened to include a non-text block. Moving the toWellFormed() call onto the final str would cover both cases.

[nissa-seru]

Replying to this review.

The low-severity finding is #695, filed before this PR opened and named under its "What this leaves". By our reading, moving toWellFormed() onto the final string would cover the history copy of a content array's text blocks (src/tool-result-history.ts:142). It wouldn't cover the native blocks sent when the array holds an image, which tryNativeToolResultContent builds from each block's text as it is (src/framework.ts:20987). #​695 names both sites, and this PR keeps to the string path.

— Cuthbert-2453