Module activation 

SessionToolSet — per-session core + exact activated tools (Task 15, spec §7.1, §4.2).

This is bookkeeping only, not yet an execution gate: it records which configured core tools and which exactly-activated deferred tools belong to one session, pinned to the catalog generation and schema digests they were granted against. It never issues model-facing activations, exposes schemas, initializes implementations, or enforces execution.

Isolation invariants:

• a new session’s set starts with zero activations and inherits nothing from any other set;
• activation requires an exact SessionActivationGrant for this session, tool, current catalog generation, and current schema digest;
• every rejection is typed and leaves the set unchanged (no partial mutation);
• catalog drift is represented (is_stale), never silently absorbed.

Structs

ActivatedTool

One exact activation held by a session: the validated grant plus lease placeholder metadata. The grant carries the pinned catalog generation and schema digest; the trust provenance of the catalog record is pinned engine-side at activation time (the grant type in agent-core is deliberately untouched) so execution can detect a record that was removed and re-added under a different — even internally coherent — source/provenance.

AuthorizedToolCall

A fully authorized tool call: exact resolved identity plus the acquired implementation. The implementation field is private and the ONLY constructor is ExecutionGate::authorize, which acquires it strictly after every check passes — the safe path cannot reach an implementation without passing the gate.

CorePin

Per-tool pins captured when a core tool enters a session’s set: the schema digest AND the trust provenance of the catalog record at build time. Pinning provenance (not just the digest) closes the coherent- imposter hole: a tool removed and re-added under the SAME ToolId with a schema-identical body but a different, internally consistent source/provenance must still be denied at execution time.

DroppedActivation

One activation dropped by SessionToolSet::rebuilt_for_catalog.

ExecutionGate

The spec §7.1 execution gate: a pure, reusable authorization component evaluated immediately before tool implementation lookup/execution.

ResolvedToolCall

Typed resolution of an incoming API/wire tool name to the exact live runtime tool identity: the wire name as received (bounded), the runtime name it deterministically maps to (via the registry’s sanitized-name reverse mapping), and the exact catalog ToolId derived from the live tool instance itself — never from the alias. Aliases and collision suffixes therefore cannot select a different identity than the tool they deterministically resolve to.

SessionId

Typed, validated session identity (Task 15). Freely accepted unbounded strings must not name sessions; parse at the boundary instead. The same limits back SessionActivationGrant session validation, so a grant’s session id and a SessionId can never diverge in what they accept.

SessionToolSet

The small configured core set plus exact activated deferred tools for one session, pinned to the catalog generation it was built against. Core tools are pinned with the schema digest AND trust provenance of their catalog record at build time, so later drift is detectable per tool, not just per generation.

Enums

ActivationAuthority

Host-supplied activation authority for MODEL-INITIATED activation.

ActivationBasis

ActivationError

Typed failure for activating a tool in a SessionToolSet. Every variant fails closed without mutating the set.

BulkActivationError

Typed failure for deterministic bulk activation (SessionToolSet::activate_many). Every variant fails the WHOLE batch with zero partial mutation.

DropReason

Why an activation was not carried across a round-top rebuild.

ExactRevocationError

Typed failure for SessionToolSet::revoke_exact.

GrantIssuanceError

Typed failure for host grant issuance. Issuance validates the exact known ToolId, the current catalog generation/digest (pinned into the grant), and source trust — before any grant exists.

HostActivationError

Typed failure for the host activation entry points.

RuntimeLease

Runtime-lease placeholder metadata (spec §7.4 territory). Real lease acquisition/expiry arrives with MCP/extension activation work; until then every activation records that no runtime has been acquired.

SessionIdError

Typed failure for boundary parsing of SessionId.

SessionToolSetError

Typed failure for constructing a SessionToolSet.

ToolAuthorizationError

Typed execution-gate denial. Every variant is static, bounded, and metadata-only: no tool input, no schema bytes, no provider body content — only bounded identities and generation counters.

Constants

WIRE_NAME_MAX_BYTES

Byte budget for wire/tool names echoed inside typed denials. Denials are static, bounded, metadata-only strings: hostile oversize wire names must never be reflected verbatim.

Functions

activate_exact_for_user

Explicit USER-REQUESTED exact activation (spec §7.3 / PR #63 ergonomics): the host may authorize one exact known local identity without a redundant confirmation prompt. This is a host Rust API — it is never reachable from model-authored JSON and takes no confirmation boolean. Grants are session-scoped and never persisted.

activate_model_initiated

MODEL-INITIATED exact activation: requires host-supplied ActivationAuthority::ModelConfirmed. Without it, the request is denied before any grant issuance, set mutation, or schema-generation advance. All requested ids are validated and issued first; the batch applies atomically in stable ToolId order with exactly one session schema-generation advance. Grants are session-scoped, never persisted.

carry_forward_enabled

Kill-switch for carry-forward: SYNAPS_TOOLSET_CARRY_FORWARD=0 restores the zero-inherit rebuild (every catalog mutation wipes activations).

issue_exact_grant

Issue one exact session-scoped activation grant against the CURRENT catalog state. Validates: the id is a known exact cataloged capability and its source trust/provenance is consistent and verified. The grant pins the current catalog generation and schema digest. Pure: no factory invocation, no process start, no network, no set mutation.

route_session_set

Resolve the session tool set for the extension-provider route (Task 17, closing the Task 16 policy divergence): when the runtime threads its RETAINED per-stream set, the route consumes THAT set’s current state — including exact activations — at its pinned generation. The route must never silently mint a fresh default-core set for the same round. Only callers with no retained handle at all (internal/sync helpers) fall back to a fresh default-core set with zero activations under a locally minted session.

Type Aliases

RetainedSessionToolSet

The per-runtime slot that RETAINS a session’s SharedSessionToolSet across stream turns. Exact activations are session-scoped (the activate_tools contract says so), so the set that holds them must outlive a single provider turn: every turn of the same runtime tool session reconciles and reuses the retained set instead of minting a fresh, zero-activation one. Shared by Runtime clones exactly like host_tool_session; empty until the first progressive turn.

SharedSessionToolSet

One retained per-stream-session handle: activate_tools mutates the SAME set the ExecutionGate and the next provider round consume. Interior critical sections are short and never held across .await.