Module tools 

The tool contract’s bindings that live in basis.

ADR-0012 names three ways to reach one contract, mentra’s ExecutableTool. Two of them are here:

• spawn — basis’s own tool, the native binding’s only instance. ADR-0016 made it the model’s only route to a command and to a subagent. It is registered on every runtime RuntimeBuilder builds, and the two doors it replaces — mentra’s shell and task — leave the model’s roster at the same time.
• declared — the subprocess binding: .basis/tools.json declares a name, a description, a JSON schema and a command, and basis wraps that command as a tool speaking JSON over stdio. Registered per workspace, at WorkspaceBuilder::open, since a manifest is a repository’s data rather than a process’s.

The third is MCP (crate::mcp), which is mentra’s client behind a cargo feature and registers nothing of basis’s own.

The fourth: a host’s own native tool

RuntimeBuilder::with_tool registers a type the embedding program implements, in its own process — for a tool that needs context declared’s subprocesses cannot have: a client handle, a connection, which caller or conversation this call belongs to. Unlike declared, nothing about the tool is data a repository reviews; the host’s compiled code is the whole of what it does.

What with_tool stores is a Box<dyn ExecutableTool>, handed whole to mentra’s own by-value RuntimeBuilder::with_tool at build time. oops-rs/mentra#22 closed the gap that once made that impossible: mentra implements ToolDefinition and ToolExecutor for Box<T> and Arc<T> (T: ?Sized) at the traits’ owner, forwarding every method explicitly — authorization_preview included, the method a hand-written shim could silently drop and thereby present a host’s tool to the approver as its static descriptor.

Registered on the runtime, like spawn (ADR-0018’s host scope): visible to every workspace and subagent that runtime opens, not to one session.

Building one needs mentra’s own tool-authoring types, re-exported below rather than left for a host to reach through basis to a mentra dependency it would otherwise have no reason to declare directly. The set mirrors exactly what spawn’s own ExecutableTool impl uses — proof it is complete enough to write a real tool against, not a guess at what one might need.

Re-exports

pub use spawn::ChildContext;

pub use spawn::ChildSpec;

pub use spawn::DEFAULT_DELEGATION_DEPTH;

pub use spawn::SPAWN;

pub use spawn::SpawnTool;

Modules

declared

Declared subprocess tools — the workspace binding of the tool contract.

spawn

spawn — the model’s only route to a command and to a subagent.

Structs

ParallelToolContext

Execution context made available to a parallel-safe running tool.

RuntimeToolDescriptor

Runtime-facing descriptor that wraps the provider-visible tool definition.

ToolAuthorizationPreview

ToolContext

Execution context made available to a running tool.

Enums

ToolApprovalCategory

Coarse authorization grouping for runtime policy and review systems.

ToolCapability

High-level capability labels used for runtime metadata and policy decisions.

ToolDurability

Declares whether a tool call is safe to replay or persist.

ToolExecutionCategory

Declares which scheduler/orchestrator lane a tool call belongs to.

ToolSideEffectLevel

Declares how much side effect a tool may have when executed.

Traits

ExecutableTool

Runtime tool contract used by Mentra registries and execution.

ToolDefinition

Definition contract for custom tools exposed to models.

ToolExecutor

Execution contract for custom tools exposed to models.

Type Aliases

ToolResult

String result returned by Mentra tools.