[roodboi]

Fixes the cause of HACK-1777, which blocks merging #545.

Problem

MCP SDK 1.32 closes a stdio client's transport when its read buffer passes 10 MiB. Hack's 8 MiB capture budget bounds raw child output only. The result repeats that output as content text and as structuredContent, log results add data.events, and JSON escaping grows each copy. A large result could end the client's whole session.

Change

boundMcpToolResult (src/mcp/result-budget.ts) runs at the single exit of the tools/call dispatcher, so it covers every tool. It limits the serialized result to MCP_TOOL_RESULT_LIMIT_BYTES (9.5 MiB of UTF-8), which leaves 512 KiB under 10 MiB for the JSON-RPC envelope and the start of a following message in the client's last read. A result within the limit is returned unchanged.

Over the limit, data goes in this order:

1. content text. It repeats structuredContent with extra escaping, so it buys the most and loses the least. It becomes a view of at most 256 KiB, in the same JSON shape, with its own outputTruncated and cutoff. It is not removed outright, because some clients read only this channel.
2. Log tools: stdout, then whole events from the end. stdout repeats the events. Other tools: data, then the end of stdout. Omitting data matches what a capture cut already does.
3. The end of stderr. Its first 16 KiB are protected from step 2.

What a caller sees:

• A cut never splits a code point. Sizes are measured with the real serializer, in bytes.
• structuredContent that was cut has outputTruncated: true and a fixed note ending stderr.
• structuredContent that fits after step 1 is complete and has no flag. Only the text view says it was cut.
• When events are removed from a successful collection, data.cutoff is {bound: "bytes", limit: 9961472} and data.count is the number kept. data.stop_reason still says why collection stopped.
• A backend failure stays a failure with a null cutoff.
• ok and exitCode still describe the command. A command that exited 0 stays ok when its result is cut.

Docs updated: docs/reference/mcp-tools.md, docs/reference/mcp-logs.md, docs/guides/agent-first-setup.md, tests/e2e/README.md, and the comments in src/mcp/logs-contract.ts. No agent guidance changed, so nothing was regenerated.

Please check these choices

• Text-only clients get less. A client that reads only content now sees 256 KiB of a large result, not all of it. structuredContent keeps the most because the 8 MiB capture must still fit, so the text cannot share the budget equally. Clients on structuredContent are unaffected.
• Two channels can differ. On a cut result the text view has fewer events than structuredContent, and its cutoff limit is 262144. Each channel is truthful about itself, but they are no longer the same JSON.
• The note can appear in stderr of an env tool that normally has an empty one on success. The note is fixed text and carries no values.

Verified

Local runs on Bun 1.4.2 with a private temporary HOME and HACK_HOME and HACK_DAEMON_AUTOSTART_DISABLE=1, at this head.

New test, tests/mcp-tool-result-size.test.ts: 13 pass. It drives the real server over stdio with a real SDK client on default limits, using a stub HACK_MCP_COMMAND. A tee records the bytes the client reads, so the size assertion holds on any SDK version. Coverage:

• log snapshot and log tail above 8 MiB, with emoji and characters JSON escaping expands
• a complete log stream that goes over the message limit
• a non-log tool above the capture limit, and one under it that exits 0 but expands when escaped
• a text-only cut, and a small result that must stay unchanged
• the session staying usable after each result, with the SDK validating against outputSchema
• unit cases: budget edges around surrogate pairs, an oversized first event, backend failure, the stderr floor, a result with no typed payload, and an unexpected oversized field

Client-only control, with the server from unfixed origin/next on SDK 1.26 and only the client changing:

Client SDK	Server	Result
1.26	unfixed	OK, 33.7 MB result
1.32	unfixed	MCP error -32000: Connection closed
1.32	fixed	OK, 9,961,406 bytes, 1012 events, cutoff bytes / 8388608

SDK 1.32 on client and server: the #545 tree in a scratch copy, with this fix applied, passes 13 of 13.

Mutations:

Mutation	SDK	Result
Remove the bound from the dispatcher	1.26	6 fail; the size assertion sees lines up to about 68 MB
Remove the bound from the dispatcher	1.32	6 fail; Connection closed in the output
Measure string length instead of bytes	1.26	6 fail

checkByteCutoff in tests/e2e/scenarios/mcp-logs-compose.ts: unchanged, including its 8 MiB limit assertion. Reparsed events can't outgrow the 8 MiB capture unless the source JSON uses unusual number spellings, so canonical events fit the budget and the capture limit stays the one reported. The new test makes the same checks with a stub: a complete ordered prefix of whole events, and no split code point.

Gates:

• bun run --cwd packages/cli typecheck passes.
• Biome passes on changed code files.
• Focused MCP tests pass: 73 across mcp-tool-result-size, mcp-lifetime, mcp-logs-contract, mcp-inspect-tools, mcp and mcp-session-context.
• bun run docs:check passes.
• gitleaks finds no leaks over origin/next..HEAD.

Not verified

• mcp-logs-compose itself was not run locally, because it needs Docker. Its logic was read and matched with a stub, not executed. The ticket's done condition requires it to pass on SDK 1.32 defaults, so it needs a docker-e2e run on the merged result with fix: forward security pins and fixes from main to next (HACK-1758) #545. It can't prove that on this branch alone, because this branch has SDK 1.26.
• Full suite and hosted CI: the full suite was not run locally. See this PR's checks for CI.
• Real clients other than the SDK (Claude Code, Codex and others) were not measured.
• Concurrent large results: the 512 KiB margin is reasoned from how ReadBuffer drains complete lines, not tested with parallel calls.
• Published prerelease: the ticket also requires this on next and in a prerelease, which happens after merge.

🤖 Generated with Claude Code