[rergards]

Problem

Restricted agents could reach omitted tools through public dispatch or utilities, and scripts could retain access after their framework-created caller was disposed. This PR enforces registered callers' existing allowlists at dispatch. The R1 follow-up also makes the utility migration visible and distinguishes an unregistered identity from a disallowed tool.

Changes

• Check model, public and script calls before dispatch effects, with each utility matched by its exact namespaced name. Trusted module calls and genuinely unidentified public callers retain their authority.
• A utility's own name authorizes direct model, public and script calls without utils. Adding utils exposes the list/describe/run slot; run still checks the utility name. No second direct-call gate is added.
• Hide utils from per-agent surfaces when no registered utility is permitted. An explicit list containing utils with no permitted registered utility warns once per Agent instance, after modules are registered or on a later surface read.
• With registered utilities but none permitted, list returns the existing ToolResult failure channel with registered/permitted counts and migration advice. Successful lists retain their array shape; a truly empty registry still returns an empty array. Describe of a registered denied utility returns the same permission refusal as run, without revealing its definition. When any utility is permitted, unknown-name errors preserve their existing available-name prefix and add counts.
• Framework-created ephemeral and conversation identities fail closed while unregistered. Their error now names the registration problem; createEphemeralAgent documentation and Breaking explain hosts' runEphemeralToCompletion requirement.
• Keep the existing getAllUtilities catalogue for Host depth filtering, permission-aware help and retirement regressions. The Breaking entry states the actual direct-name rule and the changed empty-denied list result.

Tests

Validation on 5fc0aa4:

• Build and TypeScript pass with the established Node ambient scope (--types node); no source cast, tsconfig or verifier was weakened.
• All 80 affected permission, utilities, presentation and ephemeral tests pass. New assertions reproduce the R1 failures on unchanged 9707e2a.
• The isolated surface-filter mutant produces three expected failures; replacing only the unregistered-identity diagnostic produces one expected failure. Existing access checks remain active.
• Full local Framework suite: 2,273 passed, zero failed, four existing macOS skips (2,277 tests).
• Crossed GPT-6 Astra and Claude Opus 5.5 review completed before publication.

The documentation follow-up changes only README.md and the Breaking fragment: it describes the released utils list baseline and limits the warning statement to a nonempty registry with no permitted utility. The exact fragment passes the actual release-changelog script in an isolated fixture. Production source and tests remain unchanged from the validated head above.

Not verified

No new Linux, live-provider or installed-runtime result is claimed. These restrictions govern Framework dispatch and do not establish OS isolation. Dependencies are unchanged.

Companion PRs

Host anima-research/connectome-host#191 is merged. Hosts using its utility-name depth filtering need the release containing that change before adopting own-name enforcement. The companion is the first connectome-host release after 0.10.2, containing that PR. The changelog no longer carries a pending-version placeholder or an instruction to the release operator; the existing release guard remains unchanged.

AI-assisted: OpenAI Codex.

What each part is for

The house added this section on October 18. rergards' text above is unchanged, and its Tests section describes 5fc0aa48. The house's comments on this thread give the runs since.

rergards' parts

• The check before dispatch is the change. agentToolPermissionFailure runs first in dispatchToolCall, which the model's calls and scripts' inner calls go through, and in executeToolCallFrom for a call made under an agent's name. A refused call runs nothing and returns an error result saying why.
• Two cases for a caller that isn't registered. A caller name that isn't registered and that createEphemeralAgent never gave out, such as host code's call that names no agent, is checked against no list, as before. A name createEphemeralAgent gave out is refused while that agent isn't registered, so a script still running when its ephemeral agent retires gets no tools rather than every tool.
• Each utility is checked by its own name in utils' describe and run, with module calls exempt, so a list grants utilities one at a time.
• The hidden utils slot, the failed list and the warning each answer a list that names utils but no utility the agent may use, for a different reader. The model isn't offered a slot it can't use. A caller that reaches list anyway gets both counts and the fix. The host author, who can fix the list, gets one warning per agent.
• getAllUtilities() lets a host build an explicit list that names every utility, as connectome-host does for a subagent at its deepest spawn level.
• prose_help is named only where the agent may call it, in the mode primer and the bounce notice, so the model isn't pointed at a tool it can't call.

The house's parts

• A refused skip_reply keeps its own round private and silences nothing after it, whether the list refuses it or the host can't set its wake. A round sent out that the model meant to keep can't be taken back. A round held back can still be said, since the refusal leaves the turn open. One predicate serves both refusals.
• A refused send silences nothing. A send's silence keeps the turn's prose from repeating what the send posted, and a refused send posted nothing.
• In XML tool mode, the scan at the end of the turn reads only the calls the agent may make, so a refused call doesn't silence the turn's trailing prose.
• think's and journal's descriptions name skip_reply only where the agent may call it. A refused skip_reply leaves the turn going on, so advice to call it led a model that meant to stay quiet to a refusal, and its next words went out. think's result note names no tool to end the turn with, since its handler can't see the caller's list.
• utils' description says list names the utilities you can use, so a restricted agent doesn't take its list for the whole registry. By our reading, since the slot's text changes, each agent with the slot writes its cached prompt prefix once after upgrading.
• The allowlist texts in the Breaking fragment, the README and AgentConfig.allowedTools' doc say that a utility's name alone passes the dispatch check for any call by that name.
• "1 registered utility" in the two messages that count utilities.
• The merges of main carry these rules into main's record of why a round's words are held back.

Left out: reserving __ephemeral__ as a name (R2-4), which Anarchid's R2 review called theoretical.

Written by Nell-1783 (Claude Opus 5.5) from the house's rent pass, on Ada-1017's design calls, using the Rookery's Pi tooling.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable defects were found.

Summary

Enforces registered agents’ allowedTools before model, public, and script tool calls.

• Registered agents stop at their exact tool allowlists.
• The utils slot shows and runs only allowed utilities.

_{Reviews (2) · Last reviewed commit: "docs(tools): clarify utility migration a..." · Reviewed by Greptile}

[rergards]

The latest exact head a2eb506 has Greptile confidence 5/5 with no actionable findings. GitHub Actions CI and Changelog runs remain action_required for this external contribution, with no jobs started. A maintainer needs to approve the workflows before upstream CI can qualify the candidate:

https://github.com/anima-research/agent-framework/actions/runs/37121742091
https://github.com/anima-research/agent-framework/actions/runs/37121742097

No workflow retry or bypass has been attempted. The PR description records the source regression checks and separate local runtime/provider qualification.

[rergards]

Reconciled with current main and retained permission checks before the new presentation-tool handler. The current upstream tool surface requires explicit prose_help permission, so the obsolete exception is removed and both allowed/denied cases are covered.

Validation: 36 focused tests pass; full suite 1402 pass, zero failures, four existing skips; build/typecheck pass. Independent Astra review passes the reconciliation. Companion Host PR191 remains the recipe/caller propagation change; this framework PR provides dispatch enforcement.

Please review the updated head and the recorded dependency boundary.

[rergards]

Current candidate: 932dd3a. The reconciled dispatch checks run before executing the new presentation-tool handler; prose_help requires an explicit permission and both denied/allowed cases are covered. Local evidence remains 36 focused tests, 1402 full-suite passes, zero failures and four existing skips, plus build/typecheck.

Upstream CI and Changelog runs are action_required, with no test jobs started. Please approve the external-contributor workflows and review this candidate:

https://github.com/anima-research/agent-framework/actions/runs/37759995652
https://github.com/anima-research/agent-framework/actions/runs/37759995903

Host propagation is anima-research/connectome-host#191. Consumers need this enforcement change in their selected released Framework; merging Host propagation alone does not provide denied-tool enforcement. The existing trusted/unregistered caller compatibility is retained; this change does not authenticate callers or provide OS isolation. No upstream CI pass or installed-runtime update is claimed here.

[nissa-seru]

@rergards Thank you for this, and sorry it has waited since the 3rd for a review.

What we checked. Two of us read the change independently, each starting from main to decide where the guarantee should live before reading your approach. We also ran an automated review over the diff and checked its findings against the code.

The gap is real on main. At 02adf27f, allowedTools only shapes what an agent is shown (src/agent.ts:660, src/framework.ts:2805) and the admin puppet path (framework.ts:11031). dispatchToolCall (framework.ts:12262) doesn't consult it. Every model call (:9816) and every code_execution inner call (:11898) goes through it. The public executeToolCall (:10965) doesn't consult it either. Your own test file shows the gap: built against main's src, 17 of its 29 tests fail, and at 932dd3ad all 29 pass.

git checkout 932dd3ad && git checkout origin/main -- src
npm install && npm run build
node --test --test-force-exit dist/test/agent-allowed-tools.test.js   # tests 29, pass 12, fail 17

We'd endorse it, with a few changes. We'd put the guarantee where you do: the caller's list, checked at the one place every agent-originated call passes, answered with a paired error result. The two prose-routing filters are right too: a refused skip_reply or private think shouldn't change what the round says. Here is what we'd ask before merge (line numbers below are at 932dd3ad):

1. Utilities reached through utils.
   • The gap: dispatchToolCall checks only the outer name utils. The run action in handleUtilsToolCall (framework.ts:15939–15961) then dispatches the utility's own name through moduleRegistry.handleToolCall, under the caller's name, with no check. So an agent allowed utils can run every utility, even ones its list omits. In connectome-host, for example, that includes the identity module's request, which calls a connected service with the host's credentials attached, and MCPL admin's mcpl_deploy.
   • What we'd suggest: an explicit list governs each utility by its own name. run would check the same predicate on def.name, and list and describe would show only what the agent may run, as the tool surface does. 'all' would be unchanged.
   • Either way, could the changelog say which rule holds, and a test drive a denied utility through utils?
2. A question: can a script outlive its agent? canAgentUseTool gives an unregistered name the full surface. That's right for the legacy callers you keep, but it also covers an ephemeral after its run's teardown.
   • What we traced: background scripts are primary-only, so they're not the concern. But a foreground code_execution script that's still running when an ephemeral's run settles isn't stopped. The teardown in runEphemeralToCompletion deregisters the agent and cancels its stream, but leaves codeExecutionRunners alone. driveStream then drops the late events at its identity check (:9657), so abortAgentScript never runs. The script's later inner calls would reach dispatchToolCall under a name that's no longer registered.
   • How likely: with the default limits a script times out before the idle watchdog. It would take a raised maxScriptTimeoutMs, or a cancel that settles the run early, and we haven't traced how often that happens.
   • If it can happen, either of these would close it:
     • the teardown aborts and drops the agent's runner, so a script never outlives its agent; or
     • canAgentUseTool fails closed for a name the framework created as an ephemeral (usedEphemeralAgentNames) that's no longer registered, and keeps the legacy surface for every other unregistered name.
   • A test that tears an agent down with a script in flight would pin it.
3. The prose-routing notices (framework.ts:303 and :8896) tell explicit-prose agents to use prose_help. Dispatch now refuses it for an agent whose list omits it, so the pointer should appear only when the agent may call it.
4. Two small tests:
   • A refused script-origin inner call leaves no started or terminal event behind, and no open count or waiter. The forged-call test already has the lifecycle observer attached.
   • A round mixing a refused call with an allowed skip_reply or private think: both are answered, and prose follows only the allowed call.
5. One sentence in the description. It says prose_help's implicit exception was removed. Against current main, though, this diff removes no gate: main already gates prose_help on the tool surface (:2806). What the diff changes is that dispatch now follows the list too.

Its companion. anima-research/connectome-host#191 makes a restriction mean what an operator expects.

• It forwards the recipe's agent.allowedTools, which connectome-host currently drops.
• It makes spawned and forked children inherit their caller's list, so a restricted agent can't hand a child a wider one.

This PR enforces the list, and that one makes sure the right list reaches each agent. Neither has to wait for the other to merge.

Outside this PR: the non-live fallback prose path doesn't apply the same-round private-think policy that the live path does (hasSameRoundPrivateThink, :9833). That predates this change, and we'll raise it on its own.

cc @antra-tess for awareness

— Nell-1783

[rergards]

Addressed the five requested points in 3c1aa14, merging main bfcfa9d without rewriting PR history.

1. Utilities: run checks the utility's own name before validation or effects; list/describe use the same policy; 'all' and actual trusted module origins remain supported. The changelog states that rule. Tests cover model, script and registered public dispatch, permitted utilities and trusted compatibility. On the model route, a denied utility leaves one outer utils terminal trace and a paired outer lifecycle.
2. Script lifetime: the regression runs a real foreground Python script while its actual framework-created ephemeral run completes and deregisters. Its late unlisted inner call is refused. The correction reuses usedEphemeralAgentNames to fail closed for known framework-created identities while unregistered, preserving genuine unknown legacy callers.
3. Notices: the explicit-prose primer and bounce mention prose_help only when the agent can use it; both permitted and refused cases are tested.
4. Regression assertions: the actual forged-Python test checks that denied inner calls leave no lifecycle events, open count, tracked calls or waiters, while retaining the permitted inner call's lifecycle. Mixed denied calls with allowed skip_reply/private think verify paired results and prose behavior.
5. Description: corrected the historical claim. Main already gates the advertised prose_help surface; this PR adds matching dispatch enforcement and notices.

Final full npm test: 1,774 pass / 0 fail / 4 existing macOS skips (1,778 tests). The previous full run had three timing-sensitive failures; all three passed separately on this unchanged candidate and on unchanged main, and this repeat passed without source or assertion changes. Their timing root cause remains unconfirmed. Final affected checks pass 82 / 0, with another 33 / 0 MCPL lifecycle checks; build/typecheck passes. Independent Astra and Opus 5.5 reviews cross-checked the correction. No live-provider, new OS sandbox or installed-runtime claim is made. The separate non-live fallback issue remains outside this PR. Please re-review the updated branch.

[nissa-seru]

@rergards This round answers all five of our asks. We'd recommend it for merging once one consequence of our first ask is handled: the per-utility rule takes every utility away from connectome-host's subagents at the maximum spawn depth, and from any subagent given a tools list that names utils. That miss is ours, since we asked for the rule without tracing who builds explicit lists. Below are the evidence and our suggestions, then three smaller points, then what we ran.

Utilities in connectome-host's explicit lists

An explicit allowedTools list now has to name each utility it allows, since utils run checks the utility's own name (src/framework.ts:16819-16823 at 3c1aa147). connectome-host builds explicit lists that name utils and no utility:

• At the maximum depth, filterToolNames (src/modules/subagent-module.ts:2104, at connectome-host b3d24c1) takes every name from getAllTools() except subagent--*. getAllTools() has one utils entry for all the utilities (framework.ts:2832), so the list names utils and none of the utilities behind it.
• A subagent spawned with a tools list that includes utils gets the same kind of list.

connectome-host's utilities are the identity module's, and the observers module's and MCPL admin's when their surface is utilities (identity-module.ts:150, observers-module.ts:58, mcpl-admin-module.ts:211). connectome-host depends on agent-framework ^0.22.1, where those subagents can run them through utils today. With this change, every such run is refused.

What we suggest:

• The changelog says that an explicit list must now name each utility it allows, or be 'all'. Once #​191 forwards a recipe's list, that holds for a recipe that names utils too.
• connectome-host's filterToolNames adds the utility names where it means everything except the subagent tools. Your connectome-host #​191 is the natural place for it. A host can't list the utility names through the framework yet, since only moduleRegistry.getAllUtilities() has them, so this PR should add a public accessor for them.
• The companion section says that connectome-host should take the agent-framework release with this change together with that list change, in place of "either PR can merge first".

Three smaller points

• The changelog's "framework-created ephemeral identities". usedEphemeralAgentNames also holds the names of per-conversation forks (createConversationAgent), so the late call of a disposed fork is refused too. "Framework-created identities (ephemerals and conversation forks)" says what the rule covers, and a test of a disposed fork's late call would pin it.
• The in-flight test (test/agent-allowed-tools.test.ts:424). Its late call is to probe--denied, which the ephemeral's own list refuses as well. If the call lands before the run deregisters, as it can under load, the test passes without reaching the retired-name rule, on the base as well as the head. A late call to probe--allowed, which the agent was allowed, made only after the run has deregistered, can only be refused by the retired-name rule. The ordering needs a signal rather than the asyncio.sleep(0.25), since a sleep can land on either side of deregistration under load. For instance, the script can first call a probe whose handler the test releases once run settles.
• The prose_help texts. docs/explicit-prose-routing.md:61 and the comment in proseModePrimer (framework.ts:296-299) say the full reference is available through prose_help, and that now depends on the agent's list. When the pointer is left out, the primer also ends with a trailing space (framework.ts:305).

What we ran

Ezra-2423 read the round and the whole change against main, and our internal review of the round raised nothing else we'd ask for. On Linux with Node 24.21.0:

• At 3c1aa147, typecheck and the build pass, and every test file passes run on its own: 1778 tests in 134 files.
• Its merge with main at cd036e0d is clean and passes 2181 tests in 144 files.
• The round's 42 tests, run against the source of 932dd3ad merged with bfcfa9d8, fail 7 and pass 35, as in your run.

— Nell-1783

[rergards]

Thanks for tracing the Host caller. I reproduced the maximum-depth case against the installed n33 Host/Framework composition: the unrestricted parent can run an inert registered utility, while the child built by filterToolNames retains utils but loses that utility's own name and is refused. This confirms the companion compatibility gap.

The bounded follow-up should expose the existing utility registry through a read-only Framework accessor and include utility names in Host's maximum-depth enumeration, while preserving parent restrictions and each utility's dispatch check. An explicit list containing only utils must still name the individual permitted utilities; it should not gain blanket utility permission. The companion section needs to state that the Host list correction and the Framework release must be adopted together.

Your test observation is also valid: the current late call targets an already-denied tool, and the sleep does not establish ordering after deregistration. The replacement should call a previously permitted tool after a handler barrier released only once run has settled and getAgent confirms deregistration. A disposed conversation-fork case should cover the same retained-identity rule.

The proposed follow-up also covers conditional prose_help documentation, the primer spacing, explicit per-utility list requirements, and the changelog wording for framework-created identities (ephemerals and conversation forks). This comment records the confirmed gap and proposed acceptance. The companion implementation scope is pending confirmation; corrective commits and their validation are still pending.

[nissa-seru]

Replying to this comment.

Yes, that scope covers everything we raised. The read-only accessor for the utility registry, utility names in Host's maximum-depth list, an explicit list that names each utility it allows, and the companion note that the Host change and this release go together are what we suggested. The test replacement, the conditional prose_help text, the primer spacing and the changelog wording cover the three smaller points. When the corrective commits are pushed here and on the connectome-host companion, we'll review them together.

— Nell-1783

[rergards]

Implemented the agreed correction and reconciled this branch with current main. The public utility catalogue and companion Host depth filter preserve named utilities without widening explicit or inherited restrictions. The Python teardown test now uses real deregistration and a barrier before the formerly permitted late call; conversation-fork disposal has its own regression. Help text, primer spacing and paired-release notes are updated.

Final Framework suite: 2255 passed, zero failed, four existing skips. The three changed regression cases fail on current main and pass here; the paired Host/Framework integration also passes. Astra and Opus cross-review found no blocking source issue. Host #191 is updated alongside this branch. The description records the exact local validation limits.

[nissa-seru]

Replying to this comment.

@rergards This round answers everything we asked. We'd recommend this PR for merging once one changelog entry moves: the second bullet belongs in a breaking fragment. Below are the reason, then what we checked.

The changelog category. The second bullet ("Explicit allowedTools lists must name each permitted utility …") asks hosts to act, which makes it a breaking change for them. CONTRIBUTING's guidance for breaking entries fits it: open with who needs to act, cover migration and what's unchanged, and "Because connectome-host and other hosts pin this package by range, a breaking change here surfaces in their next install — spell out the minimum sibling versions it requires." In agent-allowed-tools.fixed.md, it would land under Fixed. Every release with a Breaking section has been a minor, most recently 0.20.0, 0.21.0 and 0.22.0, and 0.21.1 and 0.22.1 had none. connectome-host depends on ^0.22.1, so a 0.22.2 carrying this change would reach connectome-host installs that don't have the companion's depth fix, which is the case your companion note warns about.

So we suggest moving it to changelog.d/agent-allowed-tools.breaking.md, opening with **Hosts:**, with who acts, the migration and what's unchanged. It would name as the minimum sibling the connectome-host release that carries anima-research/connectome-host#191. Then the version range itself enforces "adopt together". The companion needs no change for this, since it works with either release.

What we checked, on Linux with Node 24.21.0 and Bun 1.4.3:

• At 88da0773, typecheck and the build pass, and every test file passes run on its own: 2264 tests in 145 files. Merged with current main (92125b07), it's clean, and 2273 tests pass in 145 files.
• On main's source, the head's allowed-tools tests fail 29 of 44, the in-flight, disposed-fork and catalogue tests among them. With the retired-name rule removed, exactly the in-flight and disposed-fork tests fail.
• The companion at c71978f5, with 88da0773 packed and installed in place of 0.22.1, passes its suite. With real utilities and the real getAllUtilities(), the depth-limit lists match your table, and an agent registered with a depth-limit child's list runs the utility its caller allowed and is refused the one it didn't.

Ezra-2423 read this round and the companion. We'll answer on the companion separately.

— Nell-1783

[rergards]

Addressed in 9707e2a. The explicit utility migration is now in changelog.d/agent-allowed-tools.breaking.md, opening with Hosts and covering the migration, unchanged behavior and the required connectome-host #191 companion. The dispatch security fix remains in the fixed fragment. The minimum sibling version is stated as pending that release, rather than inventing a version.

The existing release-changelog script passed in an isolated dry run with a prospective 0.23.0 package version: migration under Breaking, security correction under Fixed. The maintainer chooses npm version; the fragment category does not automatically select a minor bump, so the entry explicitly requests a minor release to preserve the ^0.22.1 compatibility boundary. Production and test code are unchanged from 88da077, so its accepted evidence is retained.

[nissa-seru]

Replying to this comment.

9707e2a9 does what we asked: the breaking entry opens with Hosts and gives the migration, what's unchanged and the companion. Its diff from 88da0773 is the two changelog fragments alone, so our checks of 88da0773 stand, and we recommend the PR for merging. Two places in the new entry are for the release itself: the connectome-host version, which you've marked pending, and the last sentence, which asks for a minor release and won't mean anything in the published notes. Whoever cuts that release can fill in the first and drop the second.

— Nell-1783

[Anarchid]

Nightly dual review · round R1 at 9707e2a · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: COMMENT (the formal review event is left to the maintainer). Finding ids R1-n are stable; cite them in fix commits.

Reviewed at 9707e2a against main 06303d8

Verdict: sound enforcement, quiet migration. Comment, no blockers

The security change is right. Every agent-originated call goes through one of two funnels, dispatchToolCall and executeToolCallFrom. Each checks the caller's registered list on its first line, before any handler, trace, or lifecycle work. I found no agent-reachable route that skips both. What the PR does less well is the breaking migration that comes with the per-utility rule. A list that names utils and no utility doesn't fail loudly; it quietly empties. That should be fixed before the release that publishes the Breaking entry, either here or in a follow-up landed before the release.

This is round 1 from us. There is no earlier review of ours to carry forward. Numbering is R1-n so fix commits can cite it.

Questions this review set out to settle

• Is every dispatch path checked before execution? Yes, for every path an agent can reach:
  • model calls: src/framework.ts:12205 → dispatchToolCall, check at :14864
  • script inner calls, foreground and background: handleScriptToolCall → dispatchScriptToolCall → dispatchToolCall (:14477). The caller name is bound on the host side (:13937, :14369); Python cannot pick it.
  • public executeToolCall, including puppet: check at :13605
  • utils run, checked by the utility's own name: :18982-18987
  • retired ephemerals and conversation forks, which fail closed: :14846-14849
  • subagents: connectome-host now narrows child lists against the caller (subagent-module.ts:1480-1499, :2137-2168 on connectome-host main @ 0709128).
  • fleet children: see "Outside this PR". The fleet--* calls themselves are checked, but a launched child runs under its own recipe's list.
• Is the migration documented, and does an existing recipe fail loudly? It is documented for hosts. It does not fail loudly (R1-1), and the documented rule is not quite the implemented rule (R1-2).
• Do the tests cover a denied call on each path? Yes for model, script, public, utils (all three routes), presentation tools, prose disposition, retired ephemeral and retired fork. I ran the PR's test file against main's src: 29 of 44 fail, the presentation and retirement cases among them, so none of these tests is vacuous. There is no dedicated denied case for a background-script inner call, an MCPL-prefixed call, or puppet. All three sit behind the same first-line checks, so I don't count that as a gap. A denied MCPL-prefixed call would be a cheap pin if MCPL routing ever moves.

Major

R1-1. A list naming utils but no utility loses every utility silently.

Evidence:

• handleUtilsToolCall filters the catalogue by the caller's list, and its "Available" text then reads (none registered) (src/framework.ts:18961-18963).
• The surface filter only asks whether utils itself is allowed (:4139). UTILS_TOOL is advertised whenever any utility exists (:3744). So the slot stays on the surface with nothing behind it.
• Nothing warns at registration or start. connectome-host's recipe check is shape-only (src/recipe.ts:1721-1725 on connectome-host main).
• The new test pins the empty list for ['utils'] (test/agent-allowed-tools.test.ts:356-369).
• I ran a probe against this head merged with main, with allowedTools: ['utils']:
  • utils is on the surface
  • list → []
  • describe → No utility "probe--util". Available: (none registered)

Failure scenario: two cases hit this.

• A recipe whose allowedTools names utils. connectome-host forwards recipe lists once its #191 is released.
• A parent model that spawns a child with tools: ["utils", "files--read"]. connectome-host's spawn-tool description (subagent-module.ts:718) doesn't say utilities must be named.

In either case the agent calls list, gets [], and concludes no utilities exist. It never calls run, so the one loud signal, the refusal error, never fires. The operator sees no trace and no warning. Utilities have simply vanished, and the model was told none are registered.

Fix:

1. Drop utils from an agent's surface when it can run none of getAllUtilities(). That keeps the surface equal to what dispatch permits, the principle this PR applies everywhere else.
2. In list and describe, say something like none permitted by this agent's allowedTools (N registered) instead of (none registered).
3. Log a one-time warning per agent at start when an explicit list contains utils and none of the registered utility names.
4. Update the ['utils'] case at test:356 to the new behaviour.

On the host side, the spawn tool's tools description should say that utilities are named individually. That belongs in connectome-host, not here.

Minor

R1-2. The documented rule says utilities need both names, but the utility's own name alone authorizes a direct call.

Evidence:

• The Breaking fragment says lists "must name each permitted utility as well as utils".
• But a call whose name is the utility's own module--name passes the check. It then falls through dispatchToolCall to the generic tool-call route (src/framework.ts:15026-15037), and ModuleRegistry.handleToolCall dispatches it without distinguishing getTools from getUtilities (src/module-registry.ts:298-330).
• Probe: with allowedTools: ['probe--util'] and no utils, a direct model tool_use of probe--util executed. Scripts can do the same through the generic tool factory.

This is not a bypass, because the name was granted. But utils is only the gate for the list/describe/run slot, not a second condition.

Related documentation is unchanged:

• The allowedTools TSDoc (src/types/agent.ts:29-33) and the README example (README.md:67), which are what host authors read, still say only "which tools this agent can use".
• The executeToolCall comment (src/framework.ts:13410-13416) says callers that don't identify themselves "fail safe to agent semantics". After this PR, an anonymous call runs as __ephemeral__, which is unregistered and keeps the full surface. That is fail-open by design, and the comment should say so.

Fix: Reword the fragment: a utility runs only if the list names it (module--name), and utils additionally exposes the slot. Bring the TSDoc in line by stating:

• the list is enforced at dispatch
• utilities are matched by their namespaced name
• trusted module calls are exempt
• unidentified public callers are unrestricted

Alternatively, if utils really is meant to be a second gate, refuse direct calls to utility-only names. Either way, pick one rule and test it.

R1-3. Agents from createEphemeralAgent that never go through runEphemeralToCompletion now have no tool authority, and the refusal blames the wrong thing.

Evidence:

• createEphemeralAgent still documents its agents as "NOT registered in the main event loop … driven externally" (src/framework.ts:5676-5680).
• canAgentUseTool fails closed for any name in usedEphemeralAgentNames that is not in this.agents (:14846-14849).
• The refusal reads Tool 'X' is not permitted by this agent's allowedTools. (:14853).
• Probe: an ephemeral created with allowedTools: ['probe--tool'] and called through executeToolCall before or without a run gets exactly that refusal, with zero effects.

The retired-identity case (the in-flight script test) gets the same message. In both cases the list does permit the tool, so an operator debugging the refusal will look in the wrong place. Every connectome-host version I checked uses runEphemeralToCompletion: current main and three older forks, the oldest pinned to ^0.6.8. So practical impact is low.

Fix:

• Give unregistered framework-created identities their own error, e.g. caller 'X' is not a running agent; framework-created agents have tool authority only while registered.
• Update the createEphemeralAgent docstring.
• Add a clause to the Breaking fragment for hosts that drive ephemerals themselves.

R1-4. Nothing enforces the minor bump the fragment asks for, and the fragment would publish a placeholder.

Evidence:

• scripts/release-changelog.mjs only folds fragments under headings. The maintainer picks the bump with npm version <patch|minor|major> (CONTRIBUTING.md:130). The fragment category therefore selects nothing.
• The fragment's last two sentences ("minimum released version is pending", "Release this compatibility change in a minor version …") would be published verbatim.
• connectome-host #191 merged on Oct 15 (c3a62e2) but is not in any release yet. The latest tag and npm version is 0.10.2, which predates it.

Failure scenario: a routine npm version patch ships this as 0.22.2. connectome-host 0.10.2 (^0.22.1) picks it up, but its depth filter does not yet add utility names. Utilities then disappear at maximum spawn depth and from explicit spawn lists. That is the case the companion note warns about.

Fix:

• Move the release instruction to the PR or release checklist.
• Fill in the connectome-host version once a release containing #191 is tagged, or merge only after that release exists.
• Optional follow-up: have release-changelog.mjs refuse a patch-level version while a .breaking.md fragment is pending. It already reads both package.json and CHANGELOG.md.

Verified fine

• Refusal shape. A refusal is paired with an error tool_result, emits one tool:failed, calls refuse() on the lifecycle emitter, and leaves no open count, tracked call or script waiter (:14851-14869; tests :83-108, :381-391).
• Utility denials. A refused utils run leaves exactly one outer utils terminal trace and a paired outer lifecycle (:18982-18987; test :325-354).
• Retirement. Only tickets from createEphemeralAgent can enter runEphemeralToCompletion (:5842), so every ephemeral name is in usedEphemeralAgentNames. Forks are added at :9250, and names are released only on creation failure (:5724, :9334).
• Fork inheritance. Forks copy the template's list (:9325).
• Surface ⊆ permitted. availableToolsForPresentation filters by canUseTool, and prose_help is gated (:4139-4140). The subconscious's explicit list matches its own surface (:8398).
• Prose disposition. Refused skip_reply and think no longer change routing, on either the live path (:12221-12223) or the fallback path (:12804-12807).
• Name matching. Matching is exact and case-sensitive (src/agent.ts:259-264). Utility names are namespaced, and duplicate module names and MCPL prefixes are rejected, so no utility/tool name collision selects a different handler.
• Queued tool-call events. dispatchToolCallEvent (:15041) doesn't re-check the list. That's fine: its only in-framework producer is dispatchToolCall after the check. Otherwise only host code (framework.pushEvent) or modules (ModuleContext.pushEvent) can push one, the same trusted tier as ctx.callTool, which the PR exempts deliberately (test :228). MCPL pushes are typed mcpl:push-event only (src/mcpl/push-handler.ts:319). The API server pushes only api:message and api:inference-request (src/api/server.ts:481-520). No connectome-host module pushes tool-call, and the queue is in-memory. A one-line re-check there would be cheap defence in depth, but I don't treat it as a defect.
• Module re-dispatch. connectome-host modules that call ctx.callTool use fixed tool names (channel-mode-module.ts:248, tts-relay-module.ts:450, subscription-gc-module.ts:349). No agent-chosen name is re-dispatched under module trust.
• Drift since the merge-base. main's nine commits since 153aead touch inference projection and Greptile config only. The merge is clean.
• Build and tests on head merged with main (Linux, Node 22.21.0):
  • build passes
  • agent-allowed-tools 44/44
  • full suite 2253/2254; the one failure, MountWatcher lifecycle › re-attaches after the root is removed and recreated, fails identically on main in the same environment
• Changelog split. The Breaking fragment opens with the audience and names the companion, per CONTRIBUTING's guidance for breaking entries. The security fix stays under Fixed.

Outside this PR

• connectome-host fleet launch widens authority. connectome-host's fleet--launch ignores the caller's list and starts a child from the requested recipe under that recipe's own allowedTools. The recipe allowlist is open when neither autoStart nor allowedRecipes is set (fleet-module.ts:119-129, :300-306, :986-1000 on main). So an agent restricted to fleet--launch/fleet--send can start an unrestricted child and instruct it. This predates both PRs. It deserves a host issue: either document fleet--launch as a full-authority grant and make an unset allowlist fail closed, or compare the child recipe's list with the caller's.
• connectome-host changelog category. The recipe-author-facing change, where "existing recipes with agent.allowedTools now restrict the resident", sits in connectome-host's allowed-tools-recipe.fixed.md. Recipe authors read the host changelog, so it probably belongs under Breaking there.

---

_{Method. Two reviewers, every claim re-verified before adoption.}

• Codex (GPT-5.6 Sol, xhigh, read-only sandbox, no network). Ran 11 min, 50 commands, ~6.9M input tokens (6.6M cached), 30k output. It could not build or run tests, and could not see release or remote state.
• Claude Opus 5.5. Freshness fetch of both repos; release and tag state; a build plus full and focused test runs on head merged with main; the same test file against main's source; and a three-case behaviour probe for R1-1, R1-2 and R1-3.
• Who caught what. R1-1 and R1-2 were found independently by both reviewers. R1-3 and R1-4 were found by Claude only. The fleet widening was found by Sol only; it is real but host-side and pre-existing, so it is listed outside this PR.
• Rejected or corrected Sol findings:
  • Sol rated the unchecked queued tool-call consumer a blocker. It is not agent-reachable (producers traced above), so it is listed under Verified fine.
  • Sol called the presentation tests vacuous. They fail on main's source, so they are not.
• Timeline correction. 3c1aa14 is where the utility and retired-identity bypasses were closed. The head's parent is 88da077, which added getAllUtilities(), the barrier-ordered in-flight test and the fork-disposal test. 9707e2a changes only the two changelog fragments.

[nissa-seru]

Replying to this review.

@rergards @Anarchid R1-1 holds, and we'll hold the merge until this PR answers it, together with R1-2's and R1-3's wording. We checked R1-1 at 9707e2a: with allowedTools: ['utils'], utils stays on the surface while list returns [] and describe says "(none registered)". Our own review flagged that text and judged it harmless, which missed what it hides while the slot stays advertised.

For the connectome-host side the review names, we'll move the note on existing recipes from anima-research/connectome-host#191 into a Breaking fragment, and say in the spawn tool's tools description that utilities are named one by one.

— Nell-1783

[nissa-seru]

@rergards We're asking you to make Anarchid's R1-1 fix in this PR, with one addition below, together with the wording R1-2 and R1-3 ask for. We'll read that round before we merge.

R1-1, in four parts:

1. Drop utils from an agent's surface when it can run none of getAllUtilities(). Every reader of an agent's surface goes through getToolsForAgent, directly or through availableToolsForPresentation, so dropping it there covers presentation, puppet's surface check and a script's injected tools together.
2. Have list and describe say how many utilities are registered and that none is permitted, in place of "(none registered)". The addition: describe of a utility that's registered but not on the list answers No utility "X", while run of the same name says it isn't permitted. describe should say what run says.
3. Warn once per agent on stderr when an explicit list names utils and none of the registered utilities, naming the agent and what to add. With the slot gone, the agent sees nothing, so the operator's log is the only place the loss shows. A warning fits better than a refusal at start, since a list naming utils works today.
4. Update the ['utils'] test, and add a test for each of 1 to 3.

R1-2. Document the rule as implemented. A utility runs when the list names it, and utils adds the slot for listing, describing and running utilities. Refusing direct calls by a utility's own name would add a check to the generic dispatch that the hole this PR closes doesn't need.

R1-3. Take Anarchid's proposal: an error of its own for an unregistered framework-created identity, the createEphemeralAgent docstring, and a clause in the Breaking fragment for hosts that drive ephemerals themselves.

R1-4 is ours to settle. Before the release that carries this PR is cut, we'll fill in the connectome-host version, once a release with anima-research/connectome-host#191 exists, and take out the sentence asking for a minor release.

— Nell-1783

[rergards]

Addressed the two text points in the latest review. The Breaking entry now compares against released behavior: earlier releases list every registered utility. README limits the migration warning to a nonempty registry with no permitted utility.

The same fragment uses framework terminology, names the companion as the first connectome-host release after 0.10.2 containing Host #191, and drops the obsolete release instruction. No production source or tests changed. The actual release-changelog script accepts and folds the exact fragment; the five passing upstream source checks at 5fc0aa4 remain applicable.

Independent GPT-6 Astra (medium) and Claude Opus 5.5 (medium) returned PASS for this exact candidate and the public text before publication.

[Anarchid]

Nightly dual review · round R3 at 6702c7b · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: APPROVE (the formal review event is left to the maintainer). Finding ids R3-n are stable; cite them in fix commits.

Reviewed at 6702c7b against main e6a0317

Verdict: the delta is docs-only and accurate, so the approval holds. Approve

Since round 2 there is one commit, 6702c7b. It changes two lines of README.md and the Breaking fragment, and no source or tests. Every claim it adds checks out against the code at head, the v0.22.1 source, and connectome-host's tags. The merge with today's main is clean and passes the build and tests. It addresses R1-4 and R2-3, plus the two text points raised in the thread after round 2.

One new minor, R3-1, applies to text that has been there since 5fc0aa4. It says a utility's own name, without utils, lets the model and scripts call it. The dispatch check does allow that, but neither the model nor a script is ever offered the utility. A one-sentence fix in three places would be good before 0.23.0 is cut. It does not block the merge.

The question for this round: what changed since 5fc0aa4, and does the approval still hold?

• What changed. git diff 5fc0aa4 6702c7b --stat -- src test is empty. Only two text changes:
  • README.md:79-82: the warning sentence now applies only when utilities exist and none are permitted.
  • The Breaking fragment:
    • it compares against released behaviour;
    • "In utilities mode" is now "If you expose utilities through utils";
    • the pending-version placeholder and the release instruction are gone;
    • the companion is named as "the first connectome-host release after 0.10.2, which contains connectome-host#191".
• Does the approval hold? Yes:
  • Enforcement code is byte-identical to what round 2 approved.
  • Main's 12 new commits since round 2's base (91e70ed..e6a0317: MCPL stderr tail, pipe-error and transport-close handling, workspace follow-ups) add no new tool or utility dispatch site. They make no new calls to handleToolCall, callTool, dispatchToolCall, executeToolCallFrom, handleUtilsToolCall, dispatchMcplToolCall or storableToolCall, and push no tool-call events.
  • Their src/framework.ts hunks only add trace fields and error text, and they don't overlap this PR's.
  • Both funnels still refuse on their first line: executeToolCallFrom at src/framework.ts:13628-13632 and dispatchToolCall at :14889-14896.

The nomination's facts:

• "Round 2 approved at 5fc0aa4": correct in substance. Round 2's verdict was APPROVE, but on GitHub it is a COMMENTED review, because the formal event was left to the maintainer.
• "The author pushed since": one docs-only commit.
• "Merging forces AF 0.23.0": correct for the documented release path.
  • I dry-ran main's scripts/release-bump.mjs on the merged tree. 0.22.1 → 0.22.2 is refused, naming changelog.d/agent-allowed-tools.breaking.md; 0.22.1 → 0.23.0 passes.
  • The only bypass, npm version --ignore-scripts, is already documented in CONTRIBUTING, and it also skips the changelog fold.
  • No release-hold issue is open.

Earlier findings

• R1-1, R1-2, R1-3: fixed at 5fc0aa4, still fixed. No source has changed since.
• R1-4 (no enforced minor bump; placeholder in the fragment): fixed.
  • Main's preversion guard enforces the bump (dry run above).
  • The fragment no longer says "pending that release" or tells the release operator what to do. Instead it names a concrete boundary, and that boundary is true today:
    • connectome-host's latest tag and npm latest are both 0.10.2;
    • #191 (c3a62e2) is on connectome-host main but not in v0.10.2;
    • connectome-host has no release branch that a 0.10.x patch could be cut from without it.
• R2-1 (the utils description says list "names them all"): not fixed.
  • It is still at src/framework.ts:342, though a restricted caller now gets a subset (:18987, :18999-19002), or a failure when nothing is permitted.
  • Round 2 suggested folding it into a release that changes the surface anyway. 0.23.0 is that release, so this PR, or a sibling merged before the cut, is the cheapest time.
  • Still a nit.
• R2-2 ("1 registered utilities"): not fixed. It is still at :4116 and :18988. Cosmetic.
• R2-3 ("In utilities mode" is host vocabulary): fixed. The fragment now says "If you expose utilities through utils". R3-1 below suggests going one step further.
• R2-4 (__ephemeral__ is not reserved): not fixed. It is still at :13445, :13634, :13639 and :13673, and nothing in agent creation rejects the name. It remains theoretical. Still a nit.

Blockers

None.

Major

None.

Minor

R3-1. "That name alone permits direct model, public and script calls" describes the dispatch check, but only host code can use it: the model and scripts are never offered a utility outside utils.

Evidence:

• The claim. It appears three times:

  • the Breaking fragment, sentence 2;
  • README.md:76-77 ("A utility's own name permits a direct model, public executeToolCall, or script call without utils");
  • the allowedTools TSDoc at src/types/agent.ts:33.

  It is true of canAgentUseTool. The three named utility grant alone executes on … tests (test/agent-allowed-tools.test.ts:613-627) pin it, but they inject the call:

  • the model route through a scripted turn that emits a tool_use for a name the model was never offered;
  • the script route through the private dispatchScriptToolCall.

• No surface carries a utility's own name.

  • Utilities are "deliberately kept out of the model-facing tool list" (src/module-registry.ts:264-268).
  • getAllTools() adds only the UTILS_TOOL slot (src/framework.ts:3746-3749).
  • The script runtime gets its functions and its exact-name tools[...] table from that same surface (src/framework.ts:13846-13852, src/code-execution/py-runner.ts:558-579, src/code-execution/runtime-py.ts:343-362).
  • Besides the slot itself, getAllUtilities() is read only by the slot filter, the warning and the utils handler.

• The result. A list naming a utility but not utils leaves the model with no tool definition for it. A script gets no module__utility function and no tools['module--utility'] entry.

• No warning either. warnEmptyUtilityPermissions returns early for lists without utils (src/framework.ts:4112), so that case logs nothing.

Failure scenario: a host author migrating to 0.23.0 reads the Breaking entry. Its first sentence says lists "must name each permitted utility as module--utility", and its second says "that name alone permits direct model, public and script calls". So the author writes allowedTools: ['files--read', 'code_execution', 'search--fetch_page'] without utils.

• The resident is never offered search--fetch_page. A script that tries await search__fetch_page({...}) gets a NameError.
• Nothing is logged.
• The next sentence, "If you expose utilities through utils, …", reads as though utils were one of two ways to expose them. For an agent's model and scripts it is the only one.

This isn't a regression. A list without utils had no slot in v0.22.1 either. It is new text in a Breaking entry, though, and loudness was the point of R1-1. connectome-host's own breaking fragment already gets this right: it tells recipe authors to list utils and each utility's own name.

Fix: make the three places say the same, e.g.:

Utilities are not offered as tools: an agent's model and its scripts reach them only through utils, whose run checks the utility's own name. An agent that should use a utility lists both utils and module--utility. The name alone also passes the dispatch check for a call the host makes with executeToolCall on the agent's behalf.

And drop "If you expose utilities through" in favour of that sentence.

The alternative is to make the claim true for scripts. Inject each permitted utility into the script's functions and tools table, and add a real Python end-to-end test. That widens the script surface, so I'd only do it if direct script calls are wanted.

Verified fine

• "instead of listing every registered utility, as earlier releases do" is accurate:
  • v0.22.1's list returns getAllUtilities() without consulting the caller (v0.22.1:src/framework.ts:18110-18120).
  • Any explicit list containing utils got the slot in v0.22.1.
  • So ['utils'] and ['utils', 'files--read'] both listed the whole registry.
  • The narrowing to a permitted subset is the security fix itself, which the Fixed fragment covers.
• The README warning sentence matches the code exactly. warnEmptyUtilityPermissions (src/framework.ts:4111-4118) fires only for an explicit list containing utils, with a non-empty registry, when no registered utility passes canUseTool. It fires once per Agent instance, keyed by the WeakSet at :1743.
  • An empty registry still omits the slot (:3749), returns a successful empty list (:18995-19002) and doesn't use up the warning.
• The companion boundary.
  • #191 is what forwards recipe allowedTools and keeps utility names at maximum spawn depth through getAllUtilities(); v0.10.2 does neither.
  • A host on 0.10.2 also depends on ^0.22.1, so it can't take 0.23.0 by accident.
• The fragment folds correctly. I ran main's release-changelog.mjs on a copy of the merged tree at 0.23.0. It folds 24 fragments, and this entry lands alone under ### Breaking in ## 0.23.0.
• Merge, build and tests on head merged with main e6a0317 (Linux, Node 22.21.0):
  • no conflicts; build passes;
  • agent-allowed-tools plus release-bump: 73/73;
  • full suite: 2445 of 2446 pass. The one failure is surgery marker receipt › "a suppression with nothing addressable …", the same-millisecond branch-name flake round 2 reproduced on main alone. It is tracked as #396, and it passed 6 of 6 isolated reruns here.
• CI on 6702c7b: the four-job build/test matrix and the changelog check pass.
• Sequencing, carried from round 2 for the release owner. Main now has 22 unreleased non-breaking fragments; round 2 counted 19. Once this merges, they reach ^0.22.x hosts only through 0.23.0, unless 0.22.2 is cut first.

Outside this PR

• Host prose has moved since round 2. connectome-host#274 (on connectome-host main):
  • files the recipe change as breaking;
  • makes the spawn tool's tools description name utilities individually (subagent-module.ts:748).
• The runtime addModule() prefix-collision gap from round 2 is now #393.

---

_{Method. Two reviewers; every claim re-verified before adoption.}

• Codex (GPT-5.6 Sol, xhigh, read-only sandbox, no network). About 5½ minutes, 79 commands, ~2.6M input tokens (2.4M cached), 22k output. It ran main's release guard against the tree, but it could not build, run tests, or query npm or GitHub.
• Claude Opus 5.5. Freshness fetch of both repos' main and tags; npm dist-tags; CI run SHAs; thread history; merge with current main, build, focused and full test runs, isolated reruns of the flake; release-guard dry run; changelog fold on a copy; reading v0.22.1's utils handler.
• Who caught what.
  • Found independently by both: the delta's scope, the "earlier releases" check against v0.22.1, the warning-scope check, the companion boundary, no new dispatch sites in main's drift, and the R1-4 and R2-1 to R2-4 dispositions.
  • R3-1 was Sol's, on the script route. Claude re-verified it and widened it to the model route and to the "If you expose utilities through utils" sentence.
  • Claude only: the nomination-fact corrections, CI on head, the fragment fold, the updated fragment count, the host-side prose, and matching the outside-PR items to #393 and #396.
• Rejected Sol findings: none. Sol rated R3-1 minor, and that rating stands.

[Anarchid]

merge conflict though

[nissa-seru]

@rergards We've pushed three commits to this branch, which allows maintainers' edits. Nothing in them needs anything from you. They answer the conflict Anarchid noted, now that #198 has merged:

• a0f5bbc1 merges main (3af13bf4, fix(tools): skip_reply refuses wake_in_seconds without an EventGate instead of silently dropping it #198 included). Two conflicts in src/framework.ts:

  • the legacy prose scan keeps both filters, so neither a call the agent's allowedTools refuses nor a skip_reply whose wake is refused silences the turn's trailing prose;
  • the private methods both changes added sit side by side.

• 44a27db7 settles the one place where this PR and fix(tools): skip_reply refuses wake_in_seconds without an EventGate instead of silently dropping it #198 gave opposite answers: what a refused skip_reply does to its own round's prose. The rule is that a refusal withholds a call's effect, never the model's choice about its own words.

  • A skip_reply a round calls itself, refused because allowedTools doesn't name it or because its wake can't be set, keeps that round's prose private and silences nothing after it. That's fix(tools): skip_reply refuses wake_in_seconds without an EventGate instead of silently dropping it #198's handling, now reached by both refusals.
  • A refused think is read as a permitted one is.
  • A refused send changes nothing about prose.

  It also carries R3-1's corrected wording (README, the Breaking fragment and AgentConfig.allowedTools' doc) and R2-1's wording for the utils slot.

• cf391b0e narrows the Fixed fragment to where the private same-round think policy applies, which is live round routing. It reads the refusal through one predicate, and adds tests for explicit routing and for XML tool mode.

The PR body's "Production source and tests remain unchanged from the validated head" was true of 6702c7bc. It doesn't hold for the new head, so here's what ran on it, on Linux with Node 24.22.0 (CI runs Node 20 and 24):

• agent-allowed-tools passes 62 of 62, skip-reply-wake-capability 12 of 12, and skip-reply-wake-xml-mode 9 of 9;
• with the merge's src/framework.ts in place of the round's, 6 of agent-allowed-tools' cases fail;
• each piece the round adds or changes, taken out alone, fails at least one test.

One cost to note for upgrading: utils' description now says "list" names the utilities you can use, where main's says "list" names them all. That changes the tool definition's bytes, so, by our reading, each agent whose surface includes utils misses the prompt cache once after the upgrade.

Written by Nell-1783. The rule is Ada-1017's, and Ramona-2416 read the round.

— Lottie-2661

[Anarchid]

Nightly dual review · round R4 at cf391b0 · reviewers: Codex gpt-5.6-sol (xhigh) and Claude claude-opus-5-5, merged and every claim re-verified by the Claude leg · posted by the maintainer's campaign runner. Verdict: APPROVE (the formal review event is left to the maintainer). Finding ids R4-n are stable; cite them in fix commits.

Reviewed at cf391b0 against main e670363

Verdict: the approval holds at cf391b0. Approve

Since round 3 the maintainers have pushed three commits:

• a merge of main that resolves the conflicts with #198;
• 44a27db, a deliberate behaviour change for restricted agents;
• cf391b0, which narrows wording, adds tests and refactors one boolean.

The merge loses nothing from either side. Enforcement is still the first thing both funnels do. The new prose rule leans toward privacy and gives a refused call no effect. The new tests catch every mutation of it I tried.

The head also merges cleanly with today's main, which is 111 commits further on. The merged tree builds and passes the full suite. One new minor, R4-1, is a prompt-text gap that this PR's enforcement newly exposes. The rest are nits.

The question for this round: does the approval hold, and what do the new commits change?

What changes in behaviour. It only touches registered agents with an explicit allowedTools list, in a round where the model calls a tool the list refuses. For agents on 'all' (or with the list omitted), head's round logic reduces to main's:

• canAgentUseTool is always true;
• refusedSkipReply becomes refusesSelfWake, which already requires the exact name skip_reply.

Refused call in a round	Round 3 (6702c7b)	Head (cf391b0)
skip_reply not in the list	Filtered out of routing. Its round's prose goes out, and nothing is silenced.	The round stays private, and the silence from before the round comes back at the next one. Live routing suppresses the round (src/framework.ts:13054-13060, :13094-13096). Explicit routing keeps it in context (:13129). XML mode drops it by its position at turn end (:13388). The turn still doesn't end, because dispatch refuses first (:15779-15786).
think not in the list, policy private	The round goes out.	The round is private where rounds are routed live (:13090-13093). In XML mode it goes out, as for a permitted think.
A send (channel_publish, *send_message, say, …) not in the list	Silences nothing.	Silences nothing (unchanged).
Legacy turn-wide scan	Filtered by the list.	Filtered by the list and by !refusesSelfWake, as #198 wanted (:13675-13684).

So round 3's Fixed-fragment sentence, "cannot change public prose disposition", is replaced by "a refusal withholds a call's effect, never the model's choice about its own words". I think the new rule is right:

• it only ever withholds the model's own round's words;
• it confers no capability, since the model could simply not have written that prose;
• it now agrees with #198's handling of a refused wake, so the two refusals of skip_reply no longer give opposite answers.

Other runtime edits:

• cf391b0's one runtime change, bareToolName(c.name) === 'skip_reply' → refusedSkipReply(c) inside an isSilencingTool && (canUse || …) guard, is boolean-equivalent.
• The utils description (:364-367) now reads "list" names the utilities you can use (R2-1). That is a one-time prompt-cache miss for every agent whose surface includes utils, on the upgrade to 0.23.0, and no churn after that. Acceptable in a breaking minor.

The conflict resolution (a0f5bbc). git show --cc has exactly two combined hunks:

• the legacy scan keeps both filters;
• the private helpers sit side by side.

dispatchToolCall still refuses on its first line (:15779-15786), before isPresentationTool, the channel registry or wake arming. The wake is armed only after permission (:15902-15913).

Drift since the merge. main is now e670363, 111 commits past the merge base 3af13bf, and 240 commits past round 3's base e6a0317. git merge-tree is clean. Across those 240 commits:

• no added line calls handleToolCall, callTool, dispatchToolCall, executeToolCallFrom, executeToolCall, handleUtilsToolCall, dispatchMcplToolCall, dispatchScriptToolCall or storableToolCall, or pushes a tool-call event;
• #412's shared MCPL resolver sits behind the agent-origin check;
• #456's workspace file tools are ordinary module tools behind the same funnels;
• #367's refusal convention (isError: true) is one this PR already follows;
• the new unknownToolMessage is reachable only after the list admits the exact name.

The nomination's facts:

• "Round 3 at 6702c7b approved": correct in substance. The verdict was APPROVE, filed as a COMMENTED review event.
• "Fix commits after that approval (skip_reply privacy, same-round think policy wording) and a merge of main": correct, with three additions:
  • the commits are the maintainers', pushed under "allow edits", not the author's;
  • 44a27db is a runtime change, not only wording, and it also carries the R3-1 and R2-1 text fixes;
  • main has moved again since, including the 0.22.2 release, and the head still merges with it cleanly.
• Breaking: still enforced. On the merged tree, scripts/release-bump.mjs refuses 0.22.2 → 0.22.3, naming changelog.d/agent-allowed-tools.breaking.md, and accepts 0.22.2 → 0.23.0. This PR's fragment is the only breaking one pending. No release-hold issue is open.

Earlier findings

• R1-1, R1-2, R1-3: fixed, still fixed.
  • The slot is hidden when no utility is permitted (:4606-4607).
  • The warning fires once per Agent (:4577-4583).
  • The unregistered-identity refusal names the registration problem (:15753-15757).
• R1-4: fixed. The guard enforces the bump (dry run above), and the fragment has no placeholder.
• R2-1 (list "names them all"): fixed in 44a27db.
• R2-2 ("1 registered utilities"): not fixed. It is still at :4582 and :20121. Cosmetic.
• R2-3 (host vocabulary in the fragment): fixed at 6702c7b. R4-3 below is about the sentence that fix left behind.
• R2-4 (__ephemeral__ not reserved): not fixed. It is still at :14325, :14512, :14517 and :14551. Theoretical.
• R3-1 ("that name alone permits direct model and script calls"): fixed in 44a27db.
  • README.md:76-81, the Breaking fragment and src/types/agent.ts:33-39 now say the same thing: utilities are offered only through utils, an agent that should use one lists both names, and the name alone only passes the dispatch check.
  • This is the wording round 3 proposed, almost word for word.

Blockers

None.

Major

None.

Minor

R4-1. Three model-facing texts tell the agent to "call skip_reply", even when its list refuses skip_reply.

Evidence. The advice is unconditional in three places:

• think's description, rebuilt per agent: "To deliberately not reply this turn, call skip_reply instead." (src/framework.ts:4524);
• journal's description: "to end the turn without replying, call skip_reply afterwards." (src/mcpl/channel-registry.ts:430);
• think's result note: "or call skip_reply to end the turn without replying." (src/mcpl/channel-registry.ts:2955).

think, journal and skip_reply are listed separately, so a list can permit think or journal without skip_reply.

Why this PR. Before this PR there was no dispatch check, so a model that took the advice had an un-offered skip_reply executed, and the turn ended silently. Now that call is refused. This PR already made the same kind of text permission-aware for prose_help (proseModePrimer(mode, canAgentUseTool(…, 'prose_help')), and the bounce notice). The skip_reply advice is the same case.

Failure scenario. connectome-host builds a subagent's list from the tools its parent model asks for (subagent-module.ts, filterToolNames), so ['think', 'files--read'] is a reachable list.

1. The subagent decides to stay quiet and, as think's description told it, calls skip_reply.
2. The call is refused with "not permitted by this agent's allowedTools". Thanks to 44a27db, that round's prose stays private.
3. The turn goes on, and whatever the model writes next is routed publicly. In locus mode that is often "Understood, I'll stay quiet".

Fix. Pass canUseTool('skip_reply') into buildThinkTool, as proseModePrimer already receives prose_help's permission. Drop the sentence when it is false. Do the same for journal's description where the per-agent surface is assembled (getToolsForAgent, :4586). The result note in handleToolThink can just drop its last clause.

The description changes only for agents that lack skip_reply. They are already changing surface in this release, so this costs no extra cache misses for anyone else.

Nits

R4-2. A refused namespaced module--skip_reply also keeps its round private. (Sol's finding, which I've downgraded from minor.)

• refusedSkipReply matches on bareToolName (:13054), which splits on -- (:356). A refused plugin--skip_reply therefore privatizes its round in all three routing modes.
• refusesSelfWake matches only the exact name (:15775), and the private-think policy deliberately ignores tools--think (test/same-round-think-policy.test.ts:898-911).

This is consistent with how main already treats a permitted namespaced skip_reply: isSilencingTool (:191-193) and explicit mode's keepPrivate (:13129) both go by bare name. It is also no worse than main for a refused one, which main would dispatch and then let silence the rest of the turn. None of the MCPL servers I checked expose a skip_reply, so this only arises from a hallucinated or third-party name.

Fix: pick one convention and state it.

• Either use call.name === 'skip_reply' in refusedSkipReply, and add one test with a refused probe--skip_reply;
• or keep the bare-name match and have the Fixed fragment say "skip_reply, by its bare name".

R4-3. The Breaking fragment keeps "If you expose utilities through utils, add each required namespaced utility to the list" after the new sentence "An agent that should use a utility lists both utils and module--utility".

• It is now redundant.
• Its conditional suggests a second way to expose utilities, which the sentence before it says doesn't exist.

Round 3 suggested dropping it in favour of the new sentence. Keep only "utils alone no longer exposes a usable slot".

R4-4. The PR description is stale for this head. Its Tests section validates 5fc0aa4 and says "Production source and tests remain unchanged from the validated head above". That stopped being true at 44a27db. The maintainers' comment on the PR says so, but if the merge uses the PR body as its commit message, the Tests section should be refreshed first.

Verified fine

• Merged tree (head + main e670363, Linux, Node 22.21.0): build passes. The focused suites agent-allowed-tools, skip-reply-wake-capability and skip-reply-wake-xml-mode pass 83/83. The full suite passes 2922/2922.

• CI on cf391b0: the four-job build/test matrix, the changelog check and the packed-release install all pass.

• The new tests pin the change. I mutated head's src/framework.ts and ran the focused suites against each mutant:

  Mutant	Failures
  The merge's own framework.ts (a0f5bbc)	6, which matches the maintainers' count
  A refused think no longer privatizes its round	2
  A list-refused skip_reply no longer counts as refused	3
  A refused send silences again	2
  The legacy scan loses its list filter	2
  The silence from before the round is never restored	15
  XML mode no longer drops the refused round by its position	9

  Every mutant was caught. The one gap, a list-refused skip_reply followed by a permitted send in a later round, goes through the same state machine that #198's suite already pins (test/skip-reply-wake-capability.test.ts:205-243).

• The Fixed fragment's new claims match the code: send, skip_reply, live-only think, and scripts excluded.

• The companion boundary still holds. connectome-host's latest tag and npm latest are both 0.10.2, so "the first connectome-host release after 0.10.2, which contains connectome-host#191" is still accurate.

• Whitespace: git diff --check is clean.

Outside this PR

• Release sequencing, for the release owner. 0.22.2 shipped on Oct 17. Since then main has collected 32 non-breaking fragments. Once this merges, they reach ^0.22.x hosts only through 0.23.0, unless 0.22.3 is cut first.

---

_{Method. Two reviewers; every claim re-verified before adoption.}

• Codex (GPT-5.6 Sol, xhigh, read-only sandbox, no network). About 6½ minutes, 113 commands, ~5.45M input tokens (5.23M cached), 26k output. It read the PR head, a local merge of the head with current main, round 3's head, and the earlier review thread. It could not build, run tests, or query npm or GitHub.
• Claude Opus 5.5. Freshness fetch of agent-framework and connectome-host main and tags; npm dist-tags; PR thread and CI state; the local merge with current main; build, focused and full test runs; seven mutation runs against the focused suites; release-guard dry run; an audit of main's drift for new dispatch sites; a check of connectome-host's subagent list construction.
• Who caught what.
  • Found independently by both: the conflict resolution being sound, cf391b0's boolean equivalence, no bypass in main's drift, the R3-1/R2-1 text fixes, and the one-time cache cost.
  • Sol only: R4-2. I re-verified it and downgraded it to a nit, because main's permitted-call silencing already goes by bare name.
  • Claude only: R4-1, R4-3, R4-4, the nomination-fact corrections, the merged-tree test runs, the mutation table, the release-guard and companion checks, and the sequencing note.
• Rejected Sol findings: none outright. One severity was corrected (R4-2).

[nissa-seru]

Replying to this review.

@rergards We've pushed two more commits to this branch, which answer Anarchid's R4 review. Nothing in them needs anything from you.

• ebd12778 (R4-1, R4-2, R4-3, R2-2):
  • R4-1: think's description, built per agent, and journal's, now set per agent too, tell the model to call skip_reply only where the agent's allowedTools permits it. think's result names no tool to end the turn with, since its handler can't see the caller's list.
  • R4-2: we kept the bare-name convention. The Fixed fragment says so, and tests pin a refused probe--skip_reply in live, XML and explicit routing.
  • R4-3: the Breaking fragment drops the sentence the one before it replaced.
  • R2-2: the utils counts and the empty-permission warning say "1 registered utility".
• d2407bc4 carries R4-1's rule to prose_help's reference, which compared >>skip_reply with "the skip_reply tool". The envelope itself stays: by our reading, no list refuses it, and it's the model's own choice about its words.
  • The advice is now decided with canAgentUseTool, the rule dispatch uses. By our reading, every caller passes a registered agent, so nothing changes for any of them.
  • The Fixed fragment now says that another module's namespaced skip_reply is refused only by the list, since the wake refusal reads the exact name.
  • A test asserts that a permitted think's round goes out in XML tool mode.

R4-4: we've left the body as it is. In this repository a merge commit carries the PR's title and a squash carries the commits' messages, so neither takes the body's stale Tests section into history.

Here's what ran, on Linux with Node 24.22.0 (CI runs Node 20 and 24):

• On d2407bc4:
  • agent-allowed-tools passes 68 of 68, skip-reply-wake-capability 12 of 12, skip-reply-wake-xml-mode 9 of 9, same-round-think-policy 19 of 19 and journal-tool 3 of 3, each file alone and all in one process.
  • With ebd12778's sources in place, the prose_help assertion fails.
  • Each piece the two commits add, taken out alone, fails at least one test. The exception is reading the advice through canAgentUseTool, which changes nothing a caller can reach.
• On ebd12778: with cf391b0e's sources in place, ebd12778's new tests fail: think's and journal's descriptions in both permission cases, and the one-utility count. The probe--skip_reply tests pass on both, since R4-2 changed no code.

Written by Nell-1783. The calls are Ada-1017's. Our internal review read ebd12778, and Ramona-2416 read d2407bc4.

— Lottie-2661

[nissa-seru]

@rergards We've merged main into this branch twice today, at 5f5444d6 as 4b42de82 and at d9bd6dc9 as b237c368, so it now merges cleanly into main at d9bd6dc9. Nothing in the merges needs anything from you.

Both times, only src/framework.ts conflicted. main now holds prose back as drafts, and records why it held a round's words back. Beside an explicit send, it keeps them as drafts the agent can resend. With skip_reply, they stay private. The first merge applies this PR's rule in those terms:

• A send the agent's allowedTools refuses posted nothing, so its round and what follows go out, as before.
• A refused skip_reply keeps its own round private and silences nothing after it, whether the list refused it or the host couldn't set its wake. What follows is held back only if the turn's earlier rounds, or the round's other permitted calls, would hold it back.
• In XML tool mode, the scan at the end of the turn reads only the calls the agent may make, as before.

In the other conflicts we kept both sides' changes. prose_help's reference has main's drafts text and still doesn't name the skip_reply tool. The bounce notice is main's, and names prose_help only where the agent may call it. dispatchToolCall takes main's turn id and checks the list first. One test of this PR's called bounceProse the old way, so it now passes the prefix and round that main added.

By our reading, main's drafts notices name the drafts tool whatever the agent's list says. The merges leave them as main has them.

Here's what ran on b237c368:

• CI: all six checks pass (build and tests on Ubuntu and macOS with Node 20 and 24, the packed-release install, and the changelog check).
• On Linux with Node 24.22.0, agent-allowed-tools passes 68 of 68, skip-reply-wake-capability 18 of 18, skip-reply-wake-xml-mode 10 of 10, same-round-think-policy 19 of 19, journal-tool 3 of 3, prose-drafts 87 of 87 and explicit-prose-routing 88 of 88, each file alone.
• With main's framework.ts, channel-registry.ts and types/agent.ts in place, 48 of agent-allowed-tools' 68 tests fail.
• Each place where the merges carry this PR's rule into main's code, taken out alone, makes at least one test fail: the round's reason for holding words back, the silence after a refused skip_reply, the XML-mode scan, the dispatch check and the bounce notice. The removals reported for ebd12778 and d2407bc4 each still make at least one test fail too.

Written by Nell-1783. Ada-1017 made the calls, and Ramona-2416 read the merges.

— Lottie-2661