[nissa-seru]

While a reference is marked disposition: never, the framework doesn't fetch or save its payload, and it forgets the path of any copy saved before the mark, so no stub, script object or fetch_reference names that copy. The cases where the mark is lost or comes too late are under What it leaves. agent-framework 0.27.0 and 0.28.0 say in references.d.ts that never "withholds payload AND uri from model context unconditionally". The uri half held, but nothing after parsing told never from ref, so the payload could reach the agent (Problem).

@antra-tess, we're asking you to review this before it merges. It decides how agent-framework reads RFC-005's never, and it departs from RFC-005 §12, whose sketch hands a script a never payload as a path (What it leaves).

Problem

At 0.28.0 (59d609586e), as the red-first tests and a probe show (Tests):

• a small never reference from a networked server was fetched eagerly into <mount>/refs/, and every one a script's result named was fetched on demand;
• its stub then said saved: <path>, and a script's object carried the path as savedTo;
• the agent's workspace tools could find and open the copy: ls and glob listed it, and read (for text) and read_image returned its payload in their results.

RFC-005 itself fetches and saves a never reference in its vector 03, and hands one to a script as a path in §12. So what this change keeps from the agent is the payload: no host tool puts it into the agent's context, the framework fetches and keeps none, and nothing names a copy saved before the mark, except in the cases under What it leaves.

Changes

• The mark, ReferenceRecord.payloadNever. The first never read for a uri marks its record, and nothing clears the mark while the record lives. A later delivery without never, from any server, doesn't lift it, since a server "can veto context inclusion but can never expand it" (RFC-005 §3.1). A never marks the record when it is:

  • the reference's own;
  • held by its result's claims, where the caller has them: a tool result's stub, a script's object, the eager pass and a module's demand loop. This counts inline data's never even when it comes before the reference;
  • inline data's, or an embedded resource's for its resource's uri, wherever its block is classified (classifyBlock, through markNever), for a record the uri already has.

  At the eager pass and a module's demand loop, a result's claims mark the record before anything is awaited for that result (ReferenceRegistry.markNevers), so a fetch of it can't be served first.

• A copy saved before the mark is no longer named. The first mark clears the record's saved path and verified facts, so no stub, script object or fetch_reference names or serves the copy from then on. The copy stays where it was saved, and the log names its path for the operator.

• ReferenceFetcher takes an optional withhold, with a remove(path). A fetcher built with it refuses a marked record before anything else, answers each waiting caller with the mark, stops a download at its next chunk once the payload is marked, saves nothing for a mark after the last chunk, and removes a copy saved for a record marked while it was being saved. The framework builds its fetcher with withhold. RFC-005's conformance adapter builds its own without it, so vector 03 still fetches and saves a never reference.

• The eager pass, a script's demand fetch and a module's demand loop pass a marked record over, and log no refusal for it.

• A result whose blocks the walk that reads its claims can't read, as on a value too deep to convert, a BigInt or a getter that throws, now gets no fetch from the framework on its own, in model mode or script mode. Before, the eager pass fell back to the top-level blocks' claims, so it could fetch a reference that only a nested never named. It still marks by the top-level claims it can read, and logs why it fetched nothing when the result has a reference.

• An MCPL peer's error result that a module gets through ctx.callTool now marks by the same walk as a success, nested fields included, where it read the top-level blocks only.

• markNever copies a record into each open journal before it marks it, as register does, so a journal keeps the record as it stood. A script's object still reads the mark, from the live record.

• What the agent reads of a marked record:

  • its stub ends with "a server asked that its content never reach you or your tools" (PAYLOAD_NEVER), in place of a saved path or the fetch hint;
  • fetch_reference answers with that reason, and save_recent_image says it can't be fetched for that reason;
  • a script's object has savedTo: null and the reason as unfetchable.

• A link to a marked record shows no uri (shownLinkUri), whatever later testimony says, and neither does a script's object for it. A shown uri would let any tool that can fetch it bring the payload in.

• An image by uri alone on a push, channel or injection lane, whose record is marked, becomes the reference's stub rather than a url source the provider would fetch.

• A changelog fragment, changelog.d/rfc005-never-payload.fixed.md. It also says where a marked payload's link no longer shows its uri, which 0.27.0's notes for fix(tool-results): show each block of a content array, never the array's JSON #527's links don't.

The second commit removes comments and changes no code (Tests). The third adds the fail-closed result, the error result's walk and the journal copy above, with their tests. The fourth merges main at e85c57db9a: its one conflict, in src/mcpl/references.ts where a reference's record is made, keeps main's spelling of the id's prefix from NOTICE_TAG and this change's payloadNever. For an image whose uri is marked, the fifth takes the fallback text from NOTICE_TAG, as main does for its other fallbacks; the text is still [reference]. The sixth merges main again, at 4a45766f01, 234 commits after e85c57db9a, and adds nothing of its own: git show --remerge-diff prints nothing for it, and its diff against 4a45766f01 has the same added and removed lines as the fifth commit's against e85c57db9a, 11 files, +937 −51. The seventh, 2f15c4293d, changes comments only, in src/framework.ts and src/mcpl/references.ts. Three docs now say what this change does with a never: ResultClaims says an earlier result's never doesn't give way to a later result, since it marks the uri's record for as long as the record lives, while an earlier expiry still does; shownLinkUri says a link's uri is withheld when a never marked its record, whatever the result's references say; and autoFetchReferences says no mode fetches a reference a never marked, nor from a result whose blocks can't be read for a nested never.

What it leaves

• Any server's never marks the uri's record, whichever server the record is bound to. So one server's never refuses later fetches of a uri another server delivered. That costs availability, not confidentiality, and it follows from the per-uri rule: inline data's mark has no server in hand.
• A copy saved before the mark stays in the workspace, and nothing offers its path from then on. The agent's workspace tools can still find and open it, by listing refs/ or by the path an earlier stub showed, as with the history and images the agent already has.
• The raw uri: the mark is on the record for the uri as it was sent. A later link whose uri differs only in what cleaning removes gets an unmarked record, and its line can show the cleaned text, as fix(tool-results): show each block of a content array, never the array's JSON #527's links already do for such near-alike uris.
• Eviction and restarts: past the registry's 2,000 records, or after a restart, the record and its mark are gone, and a later delivery without never makes an unmarked record.
• An inline never read before any reference for its uri marks nothing, so a later plain reference makes an unmarked record. On a push, channel or injection lane that holds within one message too, and a uri-only image before a never in one such message reaches the provider as a url.
• What the agent already has: earlier workspace states, history, and images it read before the mark, which save_recent_image can save again. The agent isn't told that what it read is now never.
• A copy marked during its own save is deleted from the workspace. If that delete fails, the log says where the copy is, and nothing tries again.
• A reference in a result whose blocks can't be read for a nested never isn't marked by that never, and the fetcher's refusal reads only the record's mark.
• RFC-005 §12: no host-mediated use of a never payload exists here, so §12's hand-off to a script isn't served. A script's output reaches the model, so this change refuses that hand-off too.

Left out, as costing more than they give: withdrawing a copy saved before the mark, a set of never uris kept apart from records, and a notice telling the agent that what it read is now never.

Tests

• test/rfc005-never-payload.test.ts is new, with 38 tests:
  • how the mark is made and kept;
  • what a marked record shows in stubs, script objects, links and a push lane;
  • a fetcher built to withhold, with one built without it fetching and saving, as vector 03 expects;
  • the framework's three fetch paths, and a result whose blocks can't be read, in model mode and script mode;
  • fetch_reference's answer for a marked record;
  • end to end, with a started framework, a workspace and a local server.
• test/save-recent-image.test.ts: a marked reference refuses with the reason and writes nothing.
• test/script-structured-references.test.ts: an MCPL peer's failure that a module gets through ctx.callTool marks the records its never names, nested fields included, and registers nothing. An MCP-only peer's failure marks nothing. A module tool's never result is passed over and shown with the reason when a server whose prefix fits the tool's name connects while its call is in flight.
• Existing tests changed to match:
  • fix(tool-results): show each block of a content array, never the array's JSON #527's lift test (tool-result-blocks.test.ts) now pins the opposite for a uri a never reference marked;
  • fix(tool-results): show an embedded resource's contents, never the no-link line #796's embedded-never link test and the inline-never link test take uris of their own for their controls;
  • five tests now expect the never reason;
  • tests where never was incidental use a plain or ref reference.

At this head, 2f15c4293d, which changes only comments since 19f2ed6a96: on Linux with Node 24.22.1, in a clean checkout of a commit with this head's tree, after a fresh npm install, tsc --noEmit and the build exit 0.

On Linux with Node 24.22.1 unless named. At 19f2ed6a96, in a clean checkout, after a fresh npm install with no lockfile and dist removed first, with chronicle 0.5.0, context-manager 0.24.1, mcpl-core 0.4.0 and membrane 0.8.0:

• Typecheck and build pass.
• Ten focused test files, built from dist: 407 of 407 pass, with the tests the merges of main brought into them. On Node 22.12.0, CI's floor, each of them passes with none failing. The ten are test/rfc005-never-payload.test.ts, test/save-recent-image.test.ts, test/mcpl-reference-fetcher.test.ts, test/tool-result-blocks.test.ts, test/script-structured-references.test.ts, test/mcpl-reference-binding.test.ts, test/mcpl-reference-fields.test.ts, test/tool-result-history.test.ts, test/mcpl-push-convert.test.ts and test/mcpl-agent-words.test.ts.
• Red first, against main: with 4a45766f01's framework.ts, references.ts, reference-fetcher.ts and convert-block.ts in place of this change's, the new file fails 37 of its 38 tests. test/save-recent-image.test.ts and test/script-structured-references.test.ts fail to load, since references.ts there has no PAYLOAD_NEVER export. test/tool-result-blocks.test.ts fails 3 of its 93 tests, and tool-result-history and mcpl-reference-fields pass.

At 5e4236f2ed, this pull request's head before the second merge of main, with context-manager 0.23.1, membrane 0.8.0 and mcpl-core 0.4.0 (the receipt names no chronicle version):

• The full suite: 8,834 tests, none failing, 62 skipped. The skips need a temporary directory that folds case or Unicode forms, which the one these ran in doesn't. CI's unforced step passes 138 of 138.

Before main was first merged in, at 56170af1bd, this pull request's head then, or a commit with its tree, unless a run names another. These receipts record no package versions unless named:

• Red first: the new file, with 0.28.0's references.ts, reference-fetcher.ts, convert-block.ts and framework.ts in place of this change's: 37 of its 38 tests fail. The one that passes pins the eviction limit, which 0.28.0 meets too.
• The third commit's fixes, red first: with the second commit's framework.ts and references.ts, three tests in the new file fail, and one in test/script-structured-references.test.ts.
• A probe at 0.28.0 and at the second commit's tree, outside this change, with a started framework, a workspace and a local server. Each run asked the framework's own fetcher for a text and a PNG reference marked never. At 0.28.0 it saved both, each stub ended saved: <path>, ls and glob listed both files, read returned the text's payload and read_image the PNG's. At the second commit's tree both fetches were refused with the reason, each stub ended with it, and ls and glob found nothing.
• Removals: 51 changes, each taking out one piece of this change, run at 56170af1bd. Every one fails at least one test.
• The second commit is comments only: with comments removed, TypeScript 5.9.3's printer prints each of the ten files it changes the same at both commits. Three controls each print differently.
• RFC-005's conformance, mcpl main 8b0e57d's check on Bun 1.4.4, at 56170af1bd's tree and at 0.28.0, with chronicle 0.4.0, context-manager 0.23.1 and membrane 0.8.0 at both: 45 of 45 schema cases and 45 of 45 host cases at both.

Not verified

• The full suite at this head: not run here. CI ran at 19f2ed6a96, and all 12 of its checks passed. At this head, 4 of its 12 checks were still running at 17:28 UTC.
• No live server: it hasn't run against a live MCPL server that marks a reference never, nor in a running resident. Only the tests' local servers and the conformance fixtures exercise it.
• The conformance corpus runs through its own adapter's fetcher, so it doesn't show the framework's withholding. The tests above do.

---

• Changelog fragment added: changelog.d/rfc005-never-payload.fixed.md.

Gordon-2414 wrote the change, on Ada-1017's design and calls, and Beth-2709 specified where an embedded resource's never marks the payload. Our internal review read three rounds of an earlier version, and no review run read anything after them. Kestrel-2409 checked what each part adds, which cut withdrawing a copy saved before the mark, and Ansel-2428 read it as an agent that meets its words would. Tabitha-2467 and Desmond-2579 read that cut and the embedded-resource change. Desmond read the change's two rebases, the second onto 0.28.0, the third commit, the first merge of main and the fifth commit, without running them. Beth-2709 and Duncan-2410 read the second merge of main, without running it, and Cordelia-2434 read the seventh commit. Lottie-2661 wrote this description, from Gordon-2414's facts.

[github-actions]

Automated review

Recommendation: needs a maintainer's decision. The change belongs, but part of it needs a maintainer's call.

Reviewed commit 4872e39 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, with concerns. This is a bug fix that makes the code do what the references module already promises: never keeps the payload out of model context, and the fix lives in the existing RFC-005 components. A maintainer still has to sign off on how it reads RFC-005, mainly the dropped §12 script hand-off and one server's never blocking a uri for every server, and on classifyBlock now changing registry state.

Findings

8 findings of medium or high severity, see the inline comments:

• Medium severity. A mark during a stalled download doesn't stop it or answer waiting callers until the next chunk or the deadline.
• Medium severity. markNever mutates a record without first copying it into open journals, breaking the journal's 'as it stood' contract.
• Medium severity, maintainability. classifyBlock now mutates the process-wide registry as a side effect of classifying.
• Medium severity. neverClaims silently falls back to top-level claims when the nested walk throws, so a nested never is ignored and the payload fetched.
• Medium severity. An error result's nested never doesn't mark, unlike the success and module paths.
• Medium severity. A copy saved before the mark stays readable by the agent's workspace tools even though the fetcher can now remove it.
• Medium severity. Any server's never (or any block run through classifyBlock) can permanently disable fetching a uri another server delivered.
• Medium severity. Every MCPL result, including register mode, now gets an extra full JSON walk of its content.

4 more findings, less severe

• Low severity, documentation, changelog.d/rfc005-never-payload.fixed.md:5. Changelog headline says a never payload no longer reaches the agent's tools, which its own last bullet contradicts. The bold lead says such a reference "no longer reaches the agent or its tools". The last bullet then says a copy saved before the mark "stays in the workspace, where the agent's workspace tools can still find it", and that eviction or a restart drops the mark. Operators who read only the headline will think a never payload is never available to tools. The lead should be qualified to match what the change actually guarantees.
• Low severity, maintainability, src/framework.ts:7120-7136. The remove hook deletes by calling the agent-facing delete tool by name instead of a workspace API. saveFile writes through the typed workspace.writeBinary API, but the new remove hook calls workspace.handleToolCall({ name: 'delete', input: { path } }) with a synthetic call id and no caller agent. This couples the framework to the tool's name, its input shape and its success and error wording, and the path goes through tool-level parsing and refusals meant for agent calls. A rename or schema change to the workspace delete tool would break this cleanup silently; the only signal would be a log line. A direct deletion method on the workspace module, like writeBinary, would match the save path.
• Low severity, test coverage, test/rfc005-never-payload.test.ts:494-503. No end-to-end test of the fetch_reference tool's answer for a marked record. The tests check getReferenceFetcher().refusal(marked) and the fetcher's fetch() result. Nothing drives dispatchFetchReferenceToolCall (framework.ts:33212) and checks the error text the agent actually gets for a marked record, fetch_reference couldn't fetch "<id>": a server asked that its content never reach you or your tools. Calling again won't change that.. That text is one of the user-facing behaviors the PR description lists, and it should have a test like save-recent-image's.
• Low severity, test coverage, test/script-structured-references.test.ts:556-569. The connect-race test now uses a plain reference, so it no longer covers a never result in that race. The test 'a module tool's result is treated when a server with a prefix that fits its name connects while its call is in flight' used to feed a never reference. It now strips disposition so that its fetched and UNBOUND_REASON assertions still pass. No other test checks that a never reference in a result whose server prefix arrives mid-call is passed over by the demand fetch and shown with PAYLOAD_NEVER. A case that keeps disposition: 'never' should be kept or added, with assertions updated to the new behavior.

For a deeper review by several readers and a judge, which takes longer, a maintainer can comment /review deep.

[github-actions]

Medium severity. A mark during a stalled download doesn't stop it or answer waiting callers until the next chunk or the deadline.

The withhold check in doFetch (line 467) runs only after reader.read() returns a chunk. Callers already inside fetch() are parked on settledBy(flight.ended, deadline) and re-check withholds only after that settles. If the server stops sending after the record is marked, the connection stays open and every joined caller, such as a fetch_reference call or the script demand loop, waits until the flight's timer or its own timeout (FETCH_TIMEOUT_MS) before it gets the mark. The PR says the fetcher "answers each waiting caller with the mark" and "stops a download" once marked. Nothing aborts the controller or wakes waiters when markPayload runs. The test uses timeoutMs: 50 for the joined caller, which hides the delay.

[github-actions]

Medium severity. markNever mutates a record without first copying it into open journals, breaking the journal's 'as it stood' contract.

register() calls keepFirst(uri) before it changes a record, so an open journal (openJournal) keeps the record as it stood when the script lane began. markNever and markNevers are reached from classifyBlock and from the demand and dispatch paths. They call markPayload directly, which sets payloadNever and deletes fetchedPath, verifiedBytes and so on, without keepFirst. A journal whose uri no registration has named since then returns the mutated live record from before(uri). So line.recordBefore, which is meant to be the model's line's view, reflects a mark the line never saw. The result fails closed today, but it contradicts the documented invariant at references.ts:761-776, and later readers of recordBefore can get wrong answers.

[github-actions]

Medium severity, maintainability. classifyBlock now mutates the process-wide registry as a side effect of classifying.

classifyBlock was a pure parser. The file header says it "Mirrors the pure module in mcpl-core-ts". It now calls referenceRegistry.markNever for inline and embedded never blocks. It is called from many places that only want to know a block's kind: tool-result-guard.ts:121, visible-content.ts:48, push-coalescer.ts:451/458, history rendering, contentClaims, inlineNeverUri's default argument and the emptiness checks. Each of those calls can now permanently mark the global singleton's records, including re-renders of old history. It also marks the global referenceRegistry even when the caller works with a separate ReferenceRegistry instance. The changed tests show the cost: mcpl-reference-fields.test.ts, tool-result-history.test.ts:214 and tool-result-blocks.test.ts:1328-1371 had to switch to new uris or dispositions so that marks left by other tests would not leak into them. Marking belongs where results are ingested (markNevers at the dispatch, eager and demand paths), not in the classifier.

[github-actions]

Medium severity. neverClaims silently falls back to top-level claims when the nested walk throws, so a nested never is ignored and the payload fetched.

neverClaims catches any throw from scriptViewClaims(content, true) and quietly returns contentClaims(content), which reads only top-level blocks. tool-result-history.ts:595-599 says that when this walk stops (data too deep, a getter that throws), the treatment must not run without the claims it reads. The module route at framework.ts:25115 follows that rule by returning a failure. Here autoFetchReferences goes on to eagerly fetch, and in script mode demand-fetch, a top-level reference whose uri only a nested block marked never. Nothing is logged, so the operator cannot see that the payload was fetched under reduced claims.

[github-actions]

Medium severity. An error result's nested never doesn't mark, unlike the success and module paths.

For an MCPL peer's error result that an in-process caller receives, the change marks only contentClaims(result.content), which covers top-level blocks. The success path (autoFetchReferences → neverClaims, which reads nested fields through scriptViewClaims) and the module demand loop (framework.ts:25114-25118) both count a never nested in a block's fields. So a failure whose only never for a uri is nested, for example in an attachment field, leaves that uri's existing record unmarked. A later fetch, stub or script object for the uri then still names and serves the payload. The new test in script-structured-references.test.ts covers only top-level never blocks in the failure.

[github-actions]

Medium severity. A copy saved before the mark stays readable by the agent's workspace tools even though the fetcher can now remove it.

markPayload deletes fetchedPath and logs where the copy is, but leaves the file in <mount>/refs/. The agent's ls, glob, read and read_image can still list and open it, and earlier stubs gave its path. This is the very exposure the PR's Problem section describes. The change adds withhold.remove and uses it only when the mark lands during a save (reference-fetcher.ts:536-544), not when it lands just after. The two timings get opposite outcomes: a mark during the save deletes the copy, while one a moment later leaves the payload where the agent can read it. Passing the remove hook to the registry, or emitting an event the framework turns into a delete, would close this.

[github-actions]

Medium severity. Any server's never (or any block run through classifyBlock) can permanently disable fetching a uri another server delivered.

markNever marks the record for a uri whichever server the record is bound to. classifyBlock calls it for any inline or embedded block. So a third-party or misbehaving MCPL server, or any content passed through a lane that classifies blocks, can send {type:'image', uri: <victim uri>, data:'x', disposition:'never'} and permanently stop the agent from fetching a reference server A delivered. fetch_reference and the eager and demand fetches are all refused for the life of the record. RFC-005 §3.1 lets a server veto inclusion of what it sends. Letting it veto other servers' references across servers is a denial-of-service between servers, which the PR accepts only as an availability cost. Restricting the mark to records bound to the sending server, or at least logging cross-server marks, would contain it.

[github-actions]

Medium severity. Every MCPL result, including register mode, now gets an extra full JSON walk of its content.

When no claims are passed, autoFetchReferences now runs neverClaims(content). That calls scriptViewClaims, which classifies every block and runs claimsInHistoryOrThrow over the whole result, nested fields included. This happens on every MCPL tool result, including the in-process register path, which fetches nothing. The results are later rendered and walked again for history, so large results pay for the walk twice. Marking only needs never claims, and the walk could be shared with the one the render already does.