[nissa-seru]

TL;DR: a tool call whose arguments membrane marks as not the model's (unparseableInput) no longer runs. The model gets an error result that says what came instead, so it can call again. A call marked as JSON null still runs, as a call with no arguments.

Closes #363.

Problem

From membrane 0.6.0 every adapter hands a call's input over as a plain object. When the model's arguments weren't one, membrane gives {} (or, for a streamed Anthropic or Bedrock call, what the block's start carried) and keeps what came in unparseableInput, on the block and on its ToolCall (ToolUseContent.unparseableInput in membrane 0.7.1's src/types/content.ts).

agent-framework ran the call with that input anyway. On main (0a4a2c6979), a module tool called with input: {} ran with {} and answered success for each of these markers:

• '{"steps": 1', cut off;
• '', a stream that ended before the call's block did;
• '[1,2]';
• '{"steps":5}', an object's JSON. membrane marks a call with this when its stream ended before the call's block stopped, or when its stream broke the API's block order and so "can't vouch for which call any arguments belong to".

For a tool whose parameters have defaults, that's a different action from the one the model asked for, carried out without a word to the model.

A call marked 'null' ran too, with whatever input its block carried. That's right when the input is {}, as it is in practice, but not when the block's start carried more.

Changes

• markedInputRefusal (src/tool-args.ts) decides. A marker whose text is JSON null reads as no arguments, as fix(tools)!: a module tool's call is checked against its schema before the module runs #372's check reads null, and the call runs with {} (asCalled). Any other marker is refused in fix(tools)!: a module tool's call is checked against its schema before the module runs #372's form, Nothing was done: <tool> <problem>.:
  • empty text, or JSON whitespace alone: "its arguments never arrived; call it again with them whole";
  • text that isn't JSON: "its arguments must be one JSON object, and this call gave text that isn't JSON, which may have been cut off:", then the start of the text, cut as fix(tools)!: a module tool's call is checked against its schema before the module runs #372 cuts a value it shows, and "call it again with one JSON object";
  • an array, a number, a string or a boolean: fix(tools)!: a module tool's call is checked against its schema before the module runs #372's own words, "its input must be an object, and this call gave an array" (one helper now writes them for both);
  • an object's JSON: "its arguments came in a response that didn't arrive whole and in order, so they can't be taken as this call's; call it again".
• Where it's read (src/framework.ts, src/module-registry.ts):
  • The round's calls, as a tool-calls event brings them, are read once with asCalled, so everything the round does with a null-marked call (its routing, its dispatch, what it stores) sees {}.
  • dispatchToolCall, after the allowedTools check, through refusedResult, so the call is refused as an allowedTools refusal is, and RFC-007's lifecycle forgets it. A script's calls can't carry the marker, since the prelude builds them from objects.
  • roundCallOf, so a round counts a refused marked call as it counts one the allowedTools refuse: a refused skip_reply keeps its own round private and silences nothing after it, and a refused send counts for nothing.
  • The turn-end routing for a turn in which no round was routed live, as when a turn's channel registry appears after its round, which leaves a refused marked call out of the calls it counts, as it leaves out one the allowedTools refuse.
  • scriptMayRoute, so a refused code_execution call leaves no round waiting for a script that never starts.
  • executeToolCallFrom, for every origin, as a failure: executeToolCall (the puppet, and a host) and a module's callTool.
  • ModuleRegistry.handleToolCall, so a queued tool-call event, and a host calling the registry, meet the same rule.
• Agent.runInference's calls keep the marker, so a caller that runs them can refuse them too, and ToolCall declares it.
• The tool-calls case's comment said every call there has valid input, which isn't so on membrane 0.7, and it's gone.
• MockMembrane carries the marker from a tool_use block to the tool-calls event and the response's toolCalls, so a test can hand the framework a marked call. F119's call (test/tool-input-null-arguments.test.ts), whose arguments text is 'null', now reaches the framework marked, and still runs.

Requirements and their tests

In test/tool-input-unparseable.test.ts unless named:

1. A model's call marked with text that isn't JSON, or with none, doesn't run, and the model gets an error result for that call naming the tool, and the start of the text where there is any. No tool lifecycle event goes out for it, and the turn goes on with that result. Tests: one per kind of marker, and one that shows only the start of a long text.
2. One marked with an array, a number, a string or a boolean doesn't run, and gets fix(tools)!: a module tool's call is checked against its schema before the module runs #372's words.
3. One marked with an object's JSON doesn't run.
4. One marked 'null' runs as a call with no arguments, whatever input its block carried, and an unmarked call runs as it came. Tests: the null test, the unmarked test, and F119's.
5. Each call of a round is decided on its own marker.
6. A refused marked skip_reply keeps its own round private and silences nothing after it, in a round routed live and in a turn where none was, and a refused marked send counts for nothing. A null-marked skip_reply counts as the call with no arguments that ran, whatever its block carried, in both.
7. A refused marked code_execution starts no script, and its round's prose goes out.
8. A marked call through executeToolCall, a module's callTool, a queued tool-call event or ModuleRegistry.handleToolCall doesn't run, and through executeToolCall it's a failure traced once, and through the registry a failure with the same text. A null-marked one, through executeToolCall or a queued event, runs with no arguments, a channel tool's included.
9. runInference's tool calls carry the marker, an empty one included.

What callers will notice

• A model whose call membrane marks gets an error result instead of the tool's answer, and can call again. A model that sends null for a call with no arguments sees no change.
• A host calling executeToolCall or ModuleRegistry.handleToolCall, or queuing a tool-call event, with a marked call gets a failure (success: false) with the same text, and its tool doesn't run. A call marked 'null' runs with no arguments.
• A host or test that reads ToolCall sees unparseableInput declared.

Not covered

• In a stream that broke the block order, a call whose arguments were JSON null reads as no arguments and runs, while the other calls of its response are refused. Its text says no arguments either way.
• XML tool mode's fallback (a round without roundContent) rebuilds the stored tool_use blocks from the calls, without the marker, as before. membrane 0.7.1's XML parsers (src/utils/tool-parser.ts, stream-parser.ts) never set the marker.
• A response that stops at max_tokens in the middle of a call yields complete, not tool-calls, so its cut-off call never ran and still doesn't, and gets no result, as before.

Overlaps

#190 adds a refusal of its own at three of the places this change reads the marker in src/framework.ts: roundCallOf, the turn-end routing's filter, and the round's calls as the tool-calls case reads them. A merge of the two conflicts there, and each place takes both conditions. In every other open pull request, a trial merge with this one conflicts only in files that already conflict with main.

Checks

At acd05ca4, on Linux with Node 24.22.1:

• The new tests and F119's: 24 of 24 pass.
• Red-first: against main's sources, 22 of the new file's 23 fail. The unmarked test passes there, as the rule leaves those calls as they were.
• The whole suite (npm run build && npm test from a clean dist): 7,595 tests, 7,551 pass, 0 fail, 44 skipped.

Written by Hilda-2580 (Claude Opus 5.5). Crispin-2406 (Claude Opus 5.5) read every commit but two: one renames a test as he asked, and one adds a next step to one refusal.

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 and fast-follow. 2 medium severity findings can be fixed after the merge.

Reviewed commit 7248206 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 bug fix belongs in the project. Calls whose arguments membrane marks as unparseableInput were running with {}.

5 reasons with sources

The change refuses them through the same refusal paths and argument-check module the framework already uses for tool dispatch, and it adds the changelog fragment and tests the contributing guide asks for.

• It fixes tool dispatch, which the project says it owns, by stopping a tool from running with arguments the model never sent. The README lists tool dispatch as one of the framework's own jobs ("Tool calls → Module.handleToolCall() → results → stream resumes"). Running a call that membrane marks as not the model's arguments, with {} or with what the block's start carried, does a different action from the one the model asked for. Refusing such a call corrects existing behavior; it doesn't add a feature. (README.md (Overview))
• The rule sits in the existing argument-check module and reuses its wording rather than adding a second way to check arguments. markedInputRefusal and asCalled sit next to toolArgsProblems. A shared notAnObject helper now writes the 'must be an object' text for both checks, so the new refusals use the same "Nothing was done:" form as #372. (src/tool-args.ts)
• Refused calls go through the framework's existing refusal paths, so they are treated like allowedTools refusals. dispatchToolCall chains the new check after agentToolPermissionFailure and returns through refusedResult. roundCallOf counts a refused marked call the same way as a refused one, and ModuleRegistry.handleToolCall applies the same rule. The separately reported turn-end fallback issue with null-marked input is a code defect for the other review, not a design departure. (src/framework.ts (dispatchToolCall, roundCallOf, refusedResult))
• It moves the framework's behavior to match the membrane upstream it depends on, which is expected for a Connectome repo. The guide says this repo sits directly on membrane. The marker is membrane's ToolUseContent.unparseableInput, and CHANGELOG.md already records membrane 0.6.0's handling of it. The one new public field is the optional ToolCall.unparseableInput, and it only passes membrane's existing marker through. (CONTRIBUTING.md (intro; How changes land))
• It follows the contribution conventions: a changelog fragment, tests for the behavior change, and a conventional-commit title. It adds changelog.d/363-unparseable-tool-input.fixed.md in the required format, plus test/tool-input-unparseable.test.ts. The mock-membrane change only carries the marker through so the tests can supply marked calls. (CONTRIBUTING.md (What a PR should contain; Changelog))

Findings

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

• Medium severity. Turn-end fallback routing reads a null-marked call's raw block input rather than the {} it ran with.
• Medium severity, test coverage. No test for a null-marked call on the turn-end fallback path, or a null-marked skip_reply in routing.

3 more findings, less severe

• Low severity, maintainability, src/framework.ts:22230-22231. markedInputFailure is passed an agent name that is never used. executeToolCallFrom calls this.markedInputFailure(call.callerAgentName ?? '__ephemeral__', call, false). With reportRefusal = false, markedInputFailure returns before it reads agentName, which only feeds refusedResult. The '__ephemeral__' fallback looks like it means something but has no effect. A reader may also think the refusal is recorded against that agent's lifecycle, which it isn't. A signature without the agent name on the failure path, mirroring how agentToolPermissionFailure is used, would be clearer.
• Low severity, documentation, src/tool-args.ts:74-96. New exported helpers markedInputRefusal and asCalled have no doc comments. Every other helper in tool-args.ts has a /** */ comment that states its contract (shown, takesNull, toolArgsProblems, etc.). The two new exports, which six call sites across framework.ts and module-registry.ts now depend on, have none. Undocumented are the return contract (undefined means run, a string is the refusal text), the special case for a 'null' marker, and the fact that asCalled keeps the marker on the call while replacing input with {}. Callers must read the body to learn that asCalled and markedInputRefusal have to be used together.
• Low severity, test coverage, test/tool-input-unparseable.test.ts:173-188. Queued-event test checks only side effects, not what the result or traces say. The test pushes two queued tool-call events and asserts only which module calls ran. It never checks the tool-result the refused queued call produces: its error text, success: false, and that it isn't marked refused. It also never checks the traces emitted for it. So the description's claim that a queued event meets 'the same rule' and answers 'with the same text, as a failure' is unverified, and the started/completed tracing of a refused call goes unnoticed.

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

[github-actions]

Medium severity. Turn-end fallback routing reads a null-marked call's raw block input rather than the {} it ran with.

In the tool-calls case the round's calls go through asCalled, so a call marked 'null' is dispatched with input: {}. The turn-end fallback path builds toolCalls from response.content and only filters with markedInputRefusal. It never applies asCalled, so refusesSelfWake(c) and silenceCauseOf read the input the block carried. Take a null-marked skip_reply whose block start carried a wake_in_seconds this host refuses. The dispatch runs it as a plain skip_reply with no arguments, which silences the turn. The fallback counts it as a refused skip_reply, which silences nothing, so trailing prose is published even though the model's skip_reply ran. Mapping the calls through asCalled here would keep the two paths in step.

[github-actions]

Medium severity, test coverage. No test for a null-marked call on the turn-end fallback path, or a null-marked skip_reply in routing.

The fallback-path test covers only a refused (non-JSON) skip_reply. No test sends a 'null'-marked call whose block carries arguments through asTurnWithNoLiveRound or through a live round with a channel registry. So nothing checks that the round's routing (roundCallOf, the fallback refusesSelfWake/silenceCauseOf) reads the same {} input the dispatch runs with. The inconsistency at framework.ts:21131-21141 passes this suite.