Tool descriptor table¶
Status¶
Accepted.
Catalog amendment (2026-11-01): after removal of git_status, the current table
has 28 model-visible rows and 27 Broker-bound manifests; ask_user remains
Host-intercepted. The original 29-row decision below records the initial scope;
counts are version-specific and are not registry invariants.
Catalog amendment (2026-11-18): ADR 0047 added the Host-intercepted advisor
row, so the current table has 29 model-visible rows and 27 Broker-bound manifests;
ask_user and advisor have no manifest.
Context¶
A model-visible tool used to be described in several hand-maintained places that had to
agree: the Protocol definition catalog, the Broker manifest list and its binding list,
the trusted adapter allowlist, the per-tool session scopes that BrokerSession mapped
from tool names, and the access class. The Broker gateway and the hook gateway each
computed their own access class. Several of these mappings had a default arm, so a
missing or mistyped entry fell through silently. The hook gateway classified unknown
tools and several mutating tools as ReadOnly, while the Broker classified the same tools
differently.
Decision¶
RuAgent.Protocol/Tools/AgentToolDescriptorTable.csis the one explicit registry of model-visible tools, with one row per tool in model order (29 rows). Each row carries its ordinal, version, description, primary and extra scopes, risk, approval requirement, adapter, workspace requirement, access class, output bound, input schema builder and example. Every value a security decision depends on is a literal on its row.AgentToolDefinitionCatalogbuilds its definitions from the table. It rejects a row whose ordinal, version or identity is wrong, a duplicate, a non-strict input schema and an example that does not validate against its schema.- The Broker derives manifests from the rows that it binds (27 rows; the Host-intercepted
ask_userhas none).ToolCatalogrequires executors and manifests to match in both directions.ToolDescriptorMappingmaps risk and adapter values through explicit arms that throw on any unmapped value. The trusted adapter allowlist inToolRegistryis derived from theAgentToolAdapterenum withHostInterceptedexcluded. After retiring ADR 0037, the set isbuiltin,desktop,terminal,web, andconnector. BrokerSessionadds to a session grant exactly the scopes of the advertised tool's row. An unknown or Host-intercepted id adds nothing.ToolAccessClassificationderives a call's access class (ReadOnly,MutationorTerminal) from the row. The Broker gateway and the hook gateway both call it. A tool without a row isTerminal. The only argument-dependent refinement is the computer tool's observation actions, which areReadOnly(ADR 0031).
Intentional behavior changes:
- Hook-gateway access classes now match the Broker's.
run_codechanges fromMutationtoTerminal.todo_write,agent_spawn,agent_send,agent_cancelandagent_applychange fromReadOnlytoMutation.mcp,ask_user,terminal_stop, non-observationcomputeractions and unknown tools change fromReadOnlytoTerminal. The class appears only on a hook-denied decision. Broker access classes are unchanged for all 28 rows. - Per-tool session scopes now equal each tool's declared scopes.
read,read_fileandrun_codeno longer addworkspace.read.listaddssystem.read.help,todo_write,skill,agent_spawn,agent_send,agent_waitandagent_cancelmove fromworkspace.readtosystem.read.agent_applyaddsworkspace.write.ask_userand unknown ids add nothing. Over the full advertised catalog the union of scopes is unchanged; a profile that advertises a subset can have a different union.
Adding a tool now requires:
- a descriptor row with its schema builder;
- an executor binding (validated in both directions by
ToolCatalog); - an explicit mapping arm for any new risk or adapter member;
- deliberate membership where the tool should be advertised: a coding profile in
AgentToolProfiles, a subagent role inSubagentRoleTools, or a program inProgramToolContract.
Consequences¶
Positive:
- Each tool is described in one place. A missing binding, schema or mapping fails at catalog construction rather than reaching the model or defaulting silently.
- Hook and Broker denials use the same access class for the same call.
Negative:
- Hook-denied decisions report a different access class for the tools listed above.
- Grants for
read,read_fileandrun_codeare narrower. Any saved behavior that relied on the previous grants changes.
Deferred¶
- Done 2026-10-30: policy-family and alias consolidation, including durable rule matching for
old operation tags.
PolicyFamilyon the descriptor row is the single source forCodingToolArguments.AdapterToolId, and legacy rule names live inAgentToolPolicyAliases;PolicyFamilyGoldenTestslocks the mapping. - Done 2026-10-30: host approval-binding derivation moved into the Broker.
AgentApprovalsServiceno longer parses tool arguments or derives matchers; the Broker returns the remember plan with the approval grant (Remembered Approval). - A persisted contract lock. The golden locks are source-level tests.
- Manifest
RequiresApprovalforweb_searchandweb_fetchis not applied by the v2 policy path.Standard_v2_web_tools_skip_approval_although_their_manifest_requires_itpins the current behavior. - Presentation labels for tools.
Verification¶
Coverage is in RuAgent.Protocol.Tests/AgentToolGoldenLockTests.cs (schema digests),
RuAgent.Broker.Tests/ToolManifestGoldenLockTests.cs (manifest security columns),
RuAgent.Broker.Tests/ToolDescriptorMappingTests.cs (unmapped values) and
RuBackend.Tests/Harness/ToolAccessClassificationTests.cs (both gateways). The implementation
record reports that the golden locks keep schema digests and manifest security columns equal to
the previous code, apart from the scope and access changes listed above.