[nissa-seru]

This fixes the RFC-014 host side released in 0.27.0 (#799), which applies to servers configured with toolHints: true.

Problem

With toolHints on, 0.27.0 has these problems. Each makes at least one test this PR adds fail on 0.27.0's code, and the tests named here are among them.

• A tools/list was taken page by page. A malformed page, or a list whose answer came after its timeout, still changed what the host believed ("a tools/list with a malformed page changes nothing the host believes", "a tools/list whose answer comes after its timeout applies nothing").
• Recovery missed two cases. A hint or toolsets/list entry naming a tool tools/list hadn't listed started no recovery ("a hint naming a tool tools/list hasn't listed is recovered from tools/list, then toolsets/list"). Nor did a list whose pages carry different mcpl/revs ("a tools/list whose pages carry different revs starts a recovery, …").
• Changes weren't told once and in order.
  • An ended record whose notice wasn't written was lost ("an ended record is told once it reaches the agent: …").
  • A told id was never forgotten, so a later record under that id wasn't heard ("a told ended id is forgotten once the server stops reporting it, …").
  • A result's change could be told after a change read later ("a result's change told as a notice comes before a later change read after it").
  • A definition counted as shown even when its notice wasn't written ("a definition first described in a notice that wasn't written is described again").
• A result's change went with it even where the result reached no agent, such as a host's own open ("an open's tool change goes with its result where the agent reads it, and as a notice for a host's own open"). A model's call answered with structured content alone showed the change and not the content ("a model's call whose result is structured content alone shows that content, then the tool change its hints made"). A change could be cut with its result's tail at the inline cap ("a model's call whose result, with its tool change after it, would pass the inline cap keeps its result whole …").
• Rendering a server's definitions could throw on a description that isn't a string, which stopped the notice or toolsets--look ("a tool a server describes malformed …").
• Smaller ones, each with a failing test:
  • a hint that moved a tool to dynamic dropped the definition it carried;
  • reminders restated servers without the pushEvents grant;
  • a first sentence could be cut inside a surrogate pair;
  • a selector that isn't a name was read as left out;
  • an open or close of unknown outcome was reported as not done;
  • a disconnect during a toolHints server's connect let it dial the server, and a stop failed it with the module's own refusal;
  • removing a server whose reconnect was pending, or restarting it under another id or with toolHints off, left toolset state behind;
  • the capability mask reported RFC-014's declarations as masked;
  • log lines printed server-chosen values unredacted;
  • a refused programmatic act wasn't traced as a failed call.

Changes

The first commit fixes the hint state, in the toolset controller and tool presence. The fifteen after it fix the wiring: how the framework's call sites use that state. The twenty after those answer reviews of the whole change and their text checks, on both sides.

Hint state

• A tool's presence is what the latest tools/list states, from the moment it's read. A hint's presence stages nothing; a move takes effect when a list states it (RFC-014 §4.1).
  • Once the next rebuild of the model's tool list that lists the server has published a move, a notice says where the tool went. A move is no reason to rebuild early, whether a hint announced it or the host's own re-read found it.
• A tools/list reaches the controller whole, as its last page is read, before anything read after it. A list whose pages carry different numeric mcpl/revs straddled a change, and the host recovers from it.
• Changes are taken only by a caller that shows them to an agent with their carrier, synchronously as the carrier is read. The caller marks them told once they reached the agent. Anything nobody took is told as a notice, in read order.
  • Without the pushEvents grant, a result's change that a notice can't carry is dropped, the framework logs the refused notice, and toolsets--look shows the state. A push keeps its change for its own path.
  • Each ended id is told once. Its note travels with it, and the id is forgotten once the server stops reporting it (§5.3).
  • A tool's first sentence is owed until text describing it reaches the model.
• A malformed definition no longer makes rendering throw. Deep nesting is cut short the same way on every runtime: a signature stops at its depth bound and writes a literal nested more than 65 levels deep as …, definition identity stops at 65 levels, and look shows JSON nested more than 65 levels deep as too deep to show, and JSON too long for the runtime to write as too long to show. Look's definition leaves out a description or class entry that isn't text.

Wiring

• A result's change goes with the result only where the result reaches an agent: the model's own call, counted once its result is handed back, and the operator's puppet, which stores its call and result in the agent's window. Elsewhere it's told as a notice. So is a dynamic tool's change that wouldn't fit whole within its result's inline cap, and the change of a call that fails after its result was read.
• Until a move applies, a tool is called wherever the model has been shown it, in the tool list last published or in the server's latest tools/list (RFC-014 §4.2: "Until it applies the move, the tool keeps working where it is"). A call by name is refused unless the tool list last published or the server's latest tools/list shows the tool static, and toolsets--act's "not a dynamic tool" unless one of them shows it dynamic. look naming a tool shows the definition act would check, wherever act would take the tool.
• An open or close whose outcome is unknown is reported as unconfirmed. It, and an act of unknown outcome, name toolsets--look, and look, which re-reads each server that presents toolsets, says when it couldn't.
• A selector that is present but isn't a name is refused (null reads as left out), and a refusal for a name the server doesn't have says what it has.
• Removing a server, or restarting it under another id or with toolHints off, forgets its toolset state. A stop or a disconnect while a toolHints server is still connecting ends the connect.
• The capability mask leaves toolHints, toolsets and surface alone, and operator tool-name patterns naming a dynamic tool count as matched.
• Server-chosen values in log lines, and in the trace of an act that can't be resolved, are redacted. A request kept for a late answer keeps only what that answer's read uses.
• A result that is structured content alone shows that content, as its JSON, before the tool change that goes with it, for the model and for the puppet; with no change, it reads as 0.27.0 read it.

Five changelog fragments say what changed since 0.27.0, by what a caller meets. One is breaking: a host that set toolHints without granting the server pushEvents now needs the grant to keep the reminder of open toolsets at an agent's next start.

What moves from 0.27.0's README

• toolsets--look naming a tool: 0.27.0's README calls what it shows "one tool's whole definition". It shows the tool's signature, description, class and input schema, as the code did, and while act would take the tool, the definition act would check.
• "Hint changes apply as their message is read" still holds, except for a move between static and dynamic, which takes effect when tools/list states it. Until the rebuild, the tool is called at either place.
• The reminder of open toolsets at an agent's next start now comes only for a server granted pushEvents (the breaking entry).
• "Each ended id is told once" becomes "once while the host runs", and rare interleavings can tell one twice.
• A dynamic tool called by its prefixed name is no longer always refused: while the tool list still offers it, the call goes through.

Tests

On Linux, with Node v24.22.1, at 2b022007 (the head, 8f71c3bb, changes one comment and the README's and fragments' text after it):

• npm test: 7,794 tests, 7,750 pass, 0 fail, 44 skipped, main's test/mcpl-toolsets-allowed-tools.test.ts among them.
• Typecheck is clean at 8f71c3bb.
• The 141 tests in the three toolsets test files (mcpl-tool-hints, mcpl-toolsets-e2e and mcpl-toolsets-wiring), run on 0.27.0's code (0a4a2c69), give 60 passes and 81 failures. Of the 81, 79 fail on their assertions, on a wait for what they test, or on reading a result that isn't there. The other 2 call a method 0.27.0 doesn't have.
• At 8f71c3bb the same three files pass on Node 24.22.1 (141 of 141) and on Node 26.12.1 (139, with the 2 tests of a result nested past what JSON.stringify can write skipped, since Node 26 writes it out).
• 44 mutations of the wiring's pieces each fail at least one toolsets test; a forty-fifth left code that didn't build, and isn't counted. They ran at 10462ef6, and include each part of the §4.2 rule (the published list alone deciding, presence alone deciding, a move told whether or not the published list shows it, and a move left pending dropped), the structured-only view (chosen on the call's taker, or kept where the change doesn't join), and a script's act reading the model's view of the result instead of the server's structured result. Two of them, which make a request kept for a late answer keep no toolset or no instance, each fail the test that a close answered after its timeout still closes its instance.

Merged with main at e7e2391f (a78a4ba8). One conflict, at the head of executeToolCallFrom in src/framework.ts: main (#804, for #363) reads the call through asCalled, and this PR adds a trace helper after it; both are kept, main's lines first.

Not verified

• A real toolHints server. Every test uses the suite's scripted servers.
• Paths with no test:
  • a push refused before the framework's push path reads it, which needs a stopping host (its mechanism, a push nobody takes being told as a notice, is tested in-process);
  • a push handler that throws;
  • the tools/list read hook's guard, which nothing known reaches; it stays as containment, since a throw there would leave the request unsettled;
  • open's and close's marking of what they told;
  • look's "(too long to show)", which needs a schema whose pretty-printed JSON passes the runtime's string length, hundreds of megabytes.
• Limits, stated rather than built for, by our reading of the code. Two have tests, named where they stand:
  • Every move reaches the tool list at the next rebuild that shows it, whatever brings it. A rebuild whose listing of a server fails publishes nothing for it and tells none of its moves. One whose listing breaks off partway (an entry it can't read) publishes what it read, as 0.27.0 did, and tells each move that list shows: a move to dynamic of a tool it no longer offers, read or not, and a move to static only for a tool it read before the break. The rest wait for the next rebuild that shows them. Until then the tool keeps working where it was, with one exception, and the agent isn't told the move. The exception: a tool moving to static that a broken-off listing never read leaves the tool list, as every tool it didn't read does; act then refuses it, naming its listed name, and a call by that name is taken. A move's note is a notice, so it follows the pushEvents grant, as every notice does (that rule's test: "a tool change with no result to ride on is a notice only where pushEvents is granted").
  • A list read while a rebuild is under way can undo a move that rebuild then publishes; neither is told, and the next rebuild puts the tool back (test: "a move a list undoes while the rebuild waits on another server is never told…").
  • While a call is in flight, the agent's window can show its result ahead of an earlier change's notice. It can also show a change after one read later: a call's result when results complete out of read order, a push's event while it waits to be stored, and a change its taker couldn't show, told as a notice when the taker finds that out.
  • A push's change counts as told once the push is accepted; if storing its event then fails, the change is lost.
  • Two definitions that differ only more than 65 levels deep count as one definition.
  • A move that changes the view is told in two notices: the view's at the read, the move's note at the rebuild.
  • A straddled list read while a recovery runs starts no other recovery; its earlier pages stand until the next change or list.
  • A server with no toolsets stops presenting them once its latest tools/list has no dynamic tool, so until the rebuild, act takes its last one only with server named.
  • When a recovery's tools/list fails, a tool its toolsets/list names that the last list lacks stays unknown until a later change or list starts a recovery.
  • A structured-only error whose content is past what the runtime's JSON.stringify can write reads as 0.27.0 read it.
  • Rendering is bounded in depth, not in size: a value too long for the runtime's strings, or a notice for more tools at once than a call takes arguments, can still throw.
  • A change that goes with the model's own call's result is counted told when the result is handed back. If the turn is stopped while the call is out, the result is dropped, and the change with it, as in 0.27.0, by a run at 0.27.0 and one at 03d1fe13 (with pushEvents granted and not); toolsets--look shows the state it left. The same holds when the agent is gone, by reading alone.
  • A result's change drained by a later read before its caller resumed, on a server without notices, is lost, not shown with its result.
  • "Told once" for ended records can fail in rare interleavings: a look held across another read of the server, an end told between a statement's build and its delivery, or ids colliding across principals under one configuration id. Told ids are kept in memory, so "once" holds while the host runs.
  • A turn cancelled or reset while a call is in flight drops that round's results, the change with them.
  • A change whose result is stored by shares, or rendered differently when stored, can still be cut with its result's tail.
  • An open's, close's or look's result is mostly its change; the inline cap cuts it as it cuts any result.
  • When the puppet's open, close or look can't store its pair, the notice that tells its change names the definitions it rendered without describing them.
  • Until the rebuild, a tool newly in a closed undeclared group stays callable by its listed name (§4.2).

What each part is for

Hint state

• Ended records.
  • ChangeSet.ended, markTold and untoldNotes mark an ended id only when its note reaches an agent, and render it only while untold.
  • The prune in adopt forgets an id once the server stops reporting it.
  • endedKeys is built from the ends that will be noted.
• Recovery and list reads.
  • ApplyOutcome.unlisted and the recovery it starts: a name tools/list hasn't listed starts a recovery. A recovery whose tools/list fails still reads toolsets/list, as 0.27.0's did.
  • RequestOptions.onRead and sendToolsList's read hook, with its pages, revs and guard: a whole list, applied as its last page is read, marked straddled (a field of its own on the read) when its pages carry different revs. The hook and the awaiting caller each gather pages with a loop, so a page too large to spread into one call's arguments can't throw after the hook has applied the list.
  • HINTED_METHODS without tools/list, and the controller's straddled read.
  • The open-list guard in readToolsetList.
• Telling changes.
  • unclaimed (ordered, with each carrier's method), tellUnclaimed, deliver and notice (told, empty or refused): what nobody took is told in read order, and only a refused push keeps its change.
  • takeChange (one public way to take a change, used inside the controller too), told and tell: the seam a caller uses to show a change and say when it reached an agent. refreshOpen returns the change it took, and a look that restates the present hands its taker each change marked blocksShown: false: told then counts none of its definitions shown, since look showed the live catalog, which counts what it rendered, while a notice that tells the change (the puppet's fallback) still shows them. changeText goes, since its callers take the change and render it.
  • isEmptyChange: whether a change has anything to take, tell or drop, read where a change is taken, told or noticed.
  • canNotify and notify's boolean on ToolsetHostDeps; the push path's finally.
• Moves. pendingMoves and applyMoves, with setTools' seen presences: the moves owed to the next rebuild. listedPresence: where the server's latest list put a tool, the half of the §4.2 rule that shownAs reads besides the published list.
• First sentences. render's mark option and its overlay of the shown set (Shown), toolBlock's seen, markShown, and showsBlock, the one rule both render and markShown use for which changes show a key's tools: a first sentence owed until it reaches the model.
• Names. The first-listing rule, and the tool-policy check for names a hint or statement gives.
• Rendering bounds. firstSentence taking any value and cutting by code points; the depth bounds in typeSig and canonicalJson, and typeSig reading a type only from text; literal, which writes a schema's enum values, const and default, … where they're nested too deeply to write, and jsonText for look, both bounded by nestsWithin at the depth canonicalJson uses rather than by a stack overflow, which comes at different depths on different Node versions, and jsonText's note for pretty-printed JSON past the runtime's string length, since nothing bounds a message's size; look's definition taking only a string description and string class entries.
• Small fixes. groups.delete in setManifest; defKeyFor's string return.
• Test helpers.
  • tappedController, which feeds a controller reads in process;
  • the scripted server's onList;
  • present, a list that moves a tool;
  • chunk, rawLine and holdingServer, the connection's reads in one synchronous run, a line written as text, and a server that holds a request until the test answers it;
  • roundTrip and nextMacrotask, waits for an effect;
  • the RFC-014 vector cases added for coverage.

Wiring

• withChangeText (framework.ts): adds a change to a ToolResult where the model's reading would have put a text block (after an error's text, as a last block, or after a string).
• withWholeChange (framework.ts): the inline-cap check for a dynamic tool's result, measured with the store's own storedToolResultText at the call's cap, the change compared as the store makes it well-formed.
• changeTaker and puppetChanges (framework.ts): who takes a call's change. The puppet's calls are keyed by call id, and the call act resolves to keeps that id, so a puppeted act needs nothing of its own; the agent's tool round names the model's own calls. The module gets it as takerFor, which it requires.
• The JSON view of a structured-only result in executeMcplToolCall, with withChange's alone (framework.ts): a change that joins such a result follows its content rather than standing in for it; without the join, a success reads as 0.27.0's and an error keeps its JSON; an error whose content is null, or past what the runtime's JSON.stringify can write, reads as 0.27.0's.
• The model dispatch's taken (framework.ts): the change between its take and the hand-off, so the dispatch's failure can tell it.
• ToolsetController's { shown } on open, close and refreshOpen, and changeOf: an unshown call leaves the change for its notice and still gets it to show its caller.
• render's describeAll and catalog's mark (tool-presence.ts): a result that may reach no agent describes every tool and counts none shown.
• renderOthers (toolsets-module.ts): the other toolsets' changes in an open's or close's answer, counted shown only where the answer reaches an agent, every tool described where it may not.
• look's couldn't-ask line (toolsets-module.ts), in its answer and in a refusal: the reader knows that what look shows of that server is what the host last knew.
• checkSelectors (toolsets-module.ts): one check at each entry point (the module's handleToolCall, resolveAct) instead of a change at each of a dozen reads.
• requestFailure and withLookHint (toolsets-module.ts): the not-sent/unconfirmed rule and the look hint in one place each; withLookHint serves open, close and act.
• withActStateHint (framework.ts): act's look hint on a failure, left out for a request known not to have been sent, which never ran.
• hintedParams (server-connection.ts): the subset of a hinted request's params that a late result's read uses.
• NONE_PRESENTS and noToolset (toolsets-module.ts): the refusals' texts, used at two and three sites.
• release (toolset-host.ts): lets go of whatever connection a controller holds, for forget.
• field, failure (toolset-host.ts): the controller's log redaction, used by its log lines.
• runDisconnectMcplServer's keepToolsets (framework.ts): a restart keeps the controller where its id and toolHints stay.
• failed (framework.ts): traces a programmatic call's refusal as tool:failed, an act's refusal redacted.
• patternableToolNames (framework.ts): replaces modelFacingToolNames, whose only caller is the pattern check.
• UNMASKABLE_KEYS gains RFC-014's three keys (capability-mask.ts).
• The connect's module wait moves under the connect's abort (framework.ts), so a stop or disconnect during a connect ends it.
• The no-agent log line (framework.ts), beside the pushEvents one.
• published (ToolsetHostDeps; framework.ts answers it) and shownAs (tool-presence.ts): the §4.2 rule in one place, read by dynamicCallRefusal and resolveAct.
• actKey (toolsets-module.ts): act's key rule for the definition it checks, shared with look naming a tool.
• moves(), applyMoves(moves) and the rebuild's movesListed (tool-presence.ts, toolset-host.ts, framework.ts): each pending move checked against the list a rebuild publishes, and told once that list shows it (a move to static once the list offers the tool, a move to dynamic once it doesn't); a move the list doesn't show yet stays pending, and a move a list has undone since isn't told.
• toolStatus's static line (tool-presence.ts) says "called by name", which holds whether or not the tool list holds the tool yet.
• makeFramework's options and hintingServer's peek (test helpers): let a test enable code execution, set agents, class overrides or the inline cap, or give the dynamic tool another definition. withPresence, movingServer and arcAndSlow (test helpers): a list that moves a tool, a server that holds the rebuild's tools/list, and a second server that holds it, so a test can stand in the window.
• heldAtModuleAdd, hintingServer, connectedTo, modelCalls, resultFor, notices, nextMacrotask and storedResult (the wiring test file):
  • a connect held at its module add, so a test can stop or disconnect in that window;
  • a toolHints server whose call answers carry a hint that shows peek;
  • a framework connected to it;
  • one model turn making the given calls;
  • what the model received for a call;
  • the tool-change notices in the window;
  • one turn of the event loop, the point by which an unclaimed change is told;
  • the puppet's stored result for a call.
• The tests: each pins one requirement, or behaviour feat(mcpl): RFC-014 tool presence and toolsets, host side (opt-in toolHints) #799 had untested.
• nestedPastStringify, stringifyOverflows and the conditional skip (test/mcpl-toolsets-wiring.test.ts): the test of a model's call whose result the host can't read needs such a result. Over JSON-RPC, the only one a peer can send is one nested past the runtime's JSON.stringify. The probe runs the test where the runtime throws on that nesting, and skips it, saying why, where the runtime writes it out (Node 26), instead of letting it pass there through the inline cap.

Questions for @antra-tess

Two designs from #799 that this PR leaves as they are, a gap in how prose routing reads act, and two smaller questions. None of them is needed for this PR. Runs use this PR's source, on Linux with Node 24.22.1, against the suite's scripted servers unless named otherwise.

1. Reminders and first sentences, decided per agent from the compile's provenance

A reminder comes due when a compiled request no longer holds a marker such as [arc/game:g1] that an earlier compile held (observeCompile, src/mcpl/toolset-host.ts line 690, through Agent.onCompiledToSend). A definition's first sentence is said once per server (ToolPresence.shown, src/mcpl/tool-presence.ts line 128).

• Run: an announcement that leaves the context before any compile carried it is never reminded. A toolset opened in a turn's tool round, with its announcement removed right after that turn, had no reminder in either of the two requests the run checked after it. With one more turn between the open and the removal, the reminder came and named it.
• Run: a second agent gets bare signatures. The resident opened game:g1, then an ephemeral run with its own store and window opened game:g2 of the same toolset. The ephemeral's window held no description of play. With nothing opened first, its window held it.
• Read:
  • Any text that keeps the marker counts as the announcement, such as the agent's own words, or a summary that kept the label and lost the signatures.
  • seen and due live in memory (toolset-host.ts lines 641–642), so after a process restart an announcement that had left the context is never reminded.

The compile already reports what it holds: each stored row by messageId with complete, and a summary as a source of kind summary (CompileProvenance in @animalabs/context-manager 0.22.0, read by noteRenderedInjections, src/agent.ts line 1375). We propose marking the row that carries each announcement, the notice or the tool result it follows, with the open toolsets it announced.

• A reminder is then due for an agent when an open toolset's latest marked row isn't whole in that agent's compile.
• A definition's first sentence is owed when no row carrying it is whole there.

That replaces the marker scan, seen, due and shown, keeps nothing in memory across restarts, and keeps the hook inside the framework rather than in Agent's public API. Is that the shape you'd want for reminders and first sentences?

2. The host's argument check, checkArgs

checkArgs (src/mcpl/tool-signature.ts line 216) is introduced as a check that "can only fail to refuse what the server would refuse on those keywords, never refuse what it would accept" (lines 173–175).

Run under Bun 1.4.4, beside ajv 8.20.0's 2020-12 validator:

• {type: "object", properties: {point: {type: "string"}}, patternProperties: {"^x-": {}}, additionalProperties: false} with {point: "d4", "x-trace": "1"}: ajv valid, while checkArgs refuses args.x-trace: not an argument of this tool.
• {type: "array", prefixItems: [{type: "string"}, {type: "number"}], items: {type: "number"}} with ["a", 1]: ajv valid, while checkArgs refuses args[0]: must be number.
• {anyOf: [{type: "object", required: ["point"]}, {type: "string"}]} with 5: both refuse, and checkArgs says args: must be object, naming only the first form.

Read:

• @animalabs/mcpl-core 0.4.0's validator fills default before it checks required (dist/src/toolsets/schema.js lines 98–104). So a call that leaves out a required key with a default runs on ToolsetServer and is refused here.
• The check's step budget counts visits, not the work in each, and anyOf/oneOf walk their first alternative again.
• Some traversals skip the budget.
• Running out of budget skips the whole check, invalid siblings included.
• The text's "the server checks every call itself" isn't something RFC-014 states: §6.1 gives the host the check.
• Of the check's own tests, the step-budget one trips the depth bound first, the bounded-time one asserts wall-clock maxima on synchronous work, and the depth-bound ones skip items, properties, additionalProperties and the alternatives.

The server already refuses a bad call with an ordinary tool error (RFC-014 §4.1). We propose dropping checkArgs. If a pre-send check is wanted, the framework's own toolArgsProblems (src/tool-args.ts line 164) checks required keys and, with values, a declared key's type and enum. That covers an instance's legal moves without a second partial JSON Schema engine. Is a pre-send check meant? If so, which validator should it agree with, JSON Schema or ToolsetServer's?

3. Prose routing for a send made through toolsets--act

Prose routing decides by a call's name whether it silences its round's prose (silenceCauseOf, src/framework.ts). A call through act has the name act, so a send that is a dynamic tool, called the only way a dynamic tool can be called, doesn't silence the round.

• Run: a ToolsetServer with toolHints: true offering say, and an agent in locus mode (the default). A round held the prose "Ordinary field speech." and a say call; the next round's prose was "turn over".
  • With say static, called by name: the server's say ran once, and both prose segments were held as drafts.
  • With say in an opened toolset, called through toolsets--act: the server's say ran once, and prose routing also published both segments to the locus, so the agent's words went out twice.
• Read: the same holds on 0.27.0. It needs a server that puts a send tool in a toolset, and we know of none that does yet.

We propose routing a call through act as the tool it resolves to would be routed if called by name, with an act that resolves to no tool silencing nothing. Is that how you'd want it?

4. Two smaller questions

• Which platform and Node version showed the code-execution-isolate-runner failure on main that feat(mcpl): RFC-014 tool presence and toolsets, host side (opt-in toolHints) #799's description names? On Linux with Node 24.22.1 it passed 88 of 88, both at feat(mcpl): RFC-014 tool presence and toolsets, host side (opt-in toolHints) #799's merge base 3b9c7dd0 and at its head b9a7bc83. The host-quiesce crash test it names failed on a loaded host when its own 60-second deadline cut short a run that finishes correctly, until test: end the quiesce crash child on its exit, not on the clock #800 removed that deadline.
• Is the invite: true a toolset notice writes into its metadata (src/framework.ts line 27712) meant for a reader outside agent-framework? Nothing in agent-framework reads it.

---

• Changelog fragments added: changelog.d/mcpl-toolsets-hint-state.breaking.md, mcpl-toolsets-hint-state.changed.md, mcpl-toolsets-hint-state.fixed.md, mcpl-toolsets-wiring.changed.md and mcpl-toolsets-wiring.fixed.md.

Written by Prudence-2217 and Octavia-2412 (Claude Opus 5.5). Ada-1017 (Claude Opus 5.5) decided its scope and shape. Jerome-2511 (Claude Opus 5.5), who built none of it, read the source against requirements read from RFC-014 and what callers meet, and Abigail-2676 (Claude Opus 5.5) weighed the tests.

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. 4 medium severity findings can be fixed after the merge.

Reviewed commit 69873a1 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 PR fixes the RFC-014 tool-presence host that the project already ships in src/mcpl/ and documents in its README. It changes existing files, adds tests and changelog fragments as CONTRIBUTING asks, and adds no new dependency, module or public concept.

5 reasons with sources

• It fixes a feature the project already documents and supports: RFC-014 tool presence for servers set to toolHints: true. The base README already describes the toolsets module, how hints are applied, recovery through tools/list then toolsets/list, notices, and the rule that each ended id is told once. The PR's fixes are about these same behaviors. (README.md, "Tool presence and toolsets (RFC-014)")
• The code stays in the components that already own this work. The hint state stays in the existing toolset controller and tool-presence files. The changes to how call sites use that state are in framework.ts, which already imported ToolsetHub and ToolsetsModule. No new module or second mechanism is added. (src/mcpl/ (toolset-host.ts, tool-presence.ts, toolsets-module.ts, tool-signature.ts) and src/framework.ts)
• The PR follows the house rules: Problem/Changes body, tests that fail on the old code, changelog fragments and README updates. It adds fragments under changelog.d/ for each category (breaking, changed, fixed), updates the README section that describes this behavior, and adds test/mcpl-toolsets-wiring.test.ts plus extensions to the existing hint tests. (CONTRIBUTING.md, "What a PR should contain" and "Changelog")
• Its two visible behavior changes come from following the RFC, and both are recorded in the changelog. First, a dynamic tool can still be called by its prefixed name until the move publishes, which the PR bases on RFC-014 §4.2. Second, reminders now require the pushEvents grant, matching the README's existing rule that notices need that grant. The second is filed as a breaking fragment, which is the project's mechanism for this kind of change. (README.md RFC-014 section; changelog.d/mcpl-toolsets-hint-state.breaking.md)
• The PR is large, but all of it concerns one feature. There are 36 commits: a hint-state fix, a wiring fix and review follow-ups, all about the toolsets host. The project merges with true merge commits and asks only that each commit be coherent. Nothing unrelated is bundled in. (CONTRIBUTING.md, "How changes land")

Findings

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

• Medium severity. A recovery whose tools/list fails gives up: no toolsets/list and no retry.
• Medium severity. A tools/list read during a recovery that straddles a change is applied and never recovered from.
• Medium severity. The model's dispatch path takes and marks a change told without checking that the agent still awaits the call.
• Medium severity. Depth-capped canonicalJson makes deep definition changes invisible to redefinition detection.

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

[github-actions]

Medium severity. A recovery whose tools/list fails gives up: no toolsets/list and no retry.

recover() now returns as soon as ownToolList returns false (if (connection !== this.connection || !read) return;). Recovery starts after a skipped or behind rev, a straddled list, or a hint that names a tool nobody listed. If its tools/list then fails or times out, the host never re-reads toolsets/list, and nothing schedules another recovery unless some other trigger sets recoverAgain during the attempt. Presence and open-instance state then stay as the lost message left them until some later hint happens to trigger a recovery. Before this change the recovery still read toolsets/list, and connected() still does when its tools/list fails, so the two paths now disagree. The recovery should be retried, for example by calling scheduleRecovery when the list fails, or should at least go on to toolsets/list as connected() does.

[github-actions]

Medium severity. A tools/list read during a recovery that straddles a change is applied and never recovered from.

readResult schedules a recovery for a straddled list only when !this.recovering. The recovery's own tools/list is the one most likely to straddle, because it is read right after a lost or out-of-order change. When it does, its older pages are applied as current, no log line is written, and no further recovery is scheduled. scheduleRecovery already guards against loops with recoverAgain, so this guard drops the one case where the rev check matters. The recovery then reads toolsets/list on top of the stale presence.

[github-actions]

Medium severity. The model's dispatch path takes and marks a change told without checking that the agent still awaits the call.

changeTaker attaches a result's change only where the agent is waiting_for_tools with call.id pending; otherwise the change is left to a notice. dispatchMcplToolCall skips that check: for any non-script MCPL peer call it calls takeChange(result), appends the change, and after pushEvent calls told(cs) (line 30521), which marks ended ids told and definitions shown. If the agent's turn was cancelled or the agent was removed while the call was out, the tool-result event may never reach a window. The change, its ended notes and first sentences are then counted as told and never reach the model. That breaks the PR's own rule that a change goes with a result only where the result reaches an agent.

[github-actions]

Medium severity. Depth-capped canonicalJson makes deep definition changes invisible to redefinition detection.

canonicalJson now returns "…" for anything nested more than 64 levels deep, and toolDigest is built from it. ToolPresence.diff decides whether a tool was redefined with toolDigest(was) !== toolDigest(d) (tool-presence.ts line 352), and shown is keyed on the same digest. Two schemas that differ only below depth 64 now get the same digest. The redefinition is therefore not reported to the agent, and the new definition's first sentence is treated as already shown. The cap stops the throw, but a cut-off marker that mixes in a hash of the rest would keep identity without the risk.