Skip to main content

Module discovery

agent_engine::tools

Module discovery 

Source
Expand description

Model-facing discovery and exact-activation builtins (Task 17, spec §4.2, §7.2, §7.3, §7.7): search_tools and activate_tools.

Both tools operate ONLY on the capability context the host injects into crate::tools::ToolCapabilities::tool_activation:

  • a PASSIVE catalog snapshot (compact descriptors + digests; reading it starts no process, touches no network, exposes no schema);
  • the RETAINED per-stream SharedSessionToolSet handle, so a confirmed activation mutates the same set the ExecutionGate and the next provider round consume;
  • a host-supplied ActivationAuthority, populated exclusively by host policy — never from model-authored JSON arguments.

search_tools returns bounded compact descriptors with stable ToolIds only — no full schemas, no factories, no source paths, no credentials. activate_tools performs deterministic atomic bulk activation of EXACT known ids through host grant issuance; source-wide, provider-wide, wildcard, unknown, and malformed identities fail typed with zero mutation. Confirmation authority is host-only: explicit host auto-approve authorizes directly; otherwise the interactive host prompt (when present) must approve the bounded exact id list with y/yes. Absent prompt or any other answer, the request is denied before any grant, set, or schema-generation mutation — model-authored JSON never confers authority.

Structs§

ActivateToolsTool
Model-initiated deterministic exact activation. Every requested id must be an exact known cataloged ToolId; the whole batch validates first (host grant issuance: exact id, current generation/digest, source trust) and applies atomically in stable id order with exactly one session schema-generation advance. Requires host-supplied confirmation authority; a model-authored JSON flag can never substitute for it.
ActivationCapability
Capability context for the discovery/activation builtins. Constructed by the host per round from the round’s catalog snapshot, the retained session-set handle, and host confirmation policy.
SearchToolsTool
Bounded, deterministic, descriptor-only capability search over the passive catalog snapshot. Pure and local: no factory invocation, no process start, no network, no schema exposure, no grant.

Constants§

ACTIVATE_TOOLS_MAX_BATCH
Maximum number of ids in one activate_tools batch.
SEARCH_TOOLS_MAX_RESULTS
Default bounded result-count budget for search_tools.
SEARCH_TOOLS_MAX_RESULT_BYTES
Default bounded serialized byte budget for search_tools hits.