Crate agentkit_tools_core 

Core abstractions for defining, registering, executing, and governing tools in agentkit.

This crate provides the Tool trait, ToolRegistry, BasicToolExecutor, and a layered permission system built on PermissionChecker, PermissionPolicy, and CompositePermissionChecker. Together these types let you:

• Define tools by implementing Tool with a ToolSpec and async invoke method.
• Register tools in a ToolRegistry and hand it to an executor or capability provider.
• Check permissions before execution using composable policies (PathPolicy, CommandPolicy, McpServerPolicy, CustomKindPolicy).
• Handle interruptions (approval prompts) via the ToolInterruption / ApprovalRequest types.
• Bridge to the capability layer with ToolCapabilityProvider, which wraps every registered tool as an Invocable.

Structs

AllowAllPermissions

A PermissionChecker that unconditionally allows every operation.

ApprovalRequest

A request sent to the host when a tool execution needs human approval.

BasicToolExecutor

The default ToolExecutor that walks one or more ToolSources, checks permissions via Tool::proposed_requests, and invokes the tool.

CatalogReader

Read side of a dynamic tool catalog. Implements ToolSource and is the value handed to [agentkit_loop::AgentBuilder::tools]. Cloning subscribes a fresh broadcast receiver, so independent observers don’t compete for catalog events.

CatalogWriter

Mutating side of a dynamic tool catalog. Owned by subsystems that discover or refresh tools at runtime (MCP server manager, skill watcher, plugin loader). Each upsert, remove, or replace_all emits a ToolCatalogEvent that every CatalogReader minted from the same dynamic_catalog call (or its clones) observes via ToolSource::drain_catalog_events.

CommandPolicy

A PermissionPolicy that governs ShellPermissionRequests by checking the executable name, working directory, and environment variables.

CompositePermissionChecker

Chains multiple PermissionPolicy implementations into a single PermissionChecker.

ConfigurableToolOutputTruncationStrategy

Configurable truncation strategy with executor-level defaults, per-tool overrides, and optional tool-metadata defaults.

CustomKindPolicy

A PermissionPolicy that matches requests whose PermissionRequest::kind starts with "custom." and allows or denies them by name.

Filtered

A ToolSource wrapper that hides tools rejected by predicate. Constructed via ToolSource::filtered or directly.

InMemoryToolOutputArtifactStore

Process-local artifact store for oversized tool results.

McpServerPolicy

A PermissionPolicy that governs McpPermissionRequests by checking whether the target server is trusted and the requested auth scopes are in the allow-list.

OwnedToolContext

Owned execution context that can outlive a single stack frame.

PathPolicy

A PermissionPolicy that governs FileSystemPermissionRequests by checking whether target paths fall within allowed or protected directory trees.

PermissionDenial

Structured denial produced when a PermissionChecker rejects an operation.

Prefixed

A ToolSource wrapper that prefixes every advertised tool name with <prefix>_. Constructed via ToolSource::prefixed or directly.

Renamed

A ToolSource wrapper that renames specific tools. Tools whose original name appears in the forward mapping are advertised under the new name and resolved from the new name back to the original. Unmapped names pass through unchanged.

ShellPermissionRequest

Permission request for executing a shell command.

ToolAnnotations

Hints that describe behavioural properties of a tool.

ToolCapabilityProvider

A CapabilityProvider that exposes every tool in a ToolRegistry as an Invocable in the agentkit capability layer.

ToolCatalogEvent

A change notification for a dynamic tool catalog.

ToolContext

Runtime context passed to every Tool::invoke call.

ToolInvocableAdapter

Wraps a Tool as an Invocable so it can be surfaced through the agentkit capability layer.

ToolName

Unique name identifying a Tool within a ToolRegistry.

ToolOutputArtifact

Stored representation of an oversized tool result.

ToolOutputArtifactId

Identifier returned when oversized tool output is stored out-of-band.

ToolOutputArtifactSlice

Bounded UTF-8 slice of a stored tool-result artifact.

ToolOutputLimit

Per-tool output limit configuration.

ToolOutputTruncationContext

Context passed to a tool-output truncation strategy after a tool invocation succeeds and before the result is appended to the transcript.

ToolRegistry

A name-keyed collection of Tool implementations.

ToolRequest

An incoming request to execute a tool.

ToolResult

The output produced by a successful tool invocation.

ToolResultReadTool

Read back a bounded slice from an oversized tool result stored by ConfigurableToolOutputTruncationStrategy.

ToolSpec

Declarative specification of a tool’s identity, schema, and behavioural hints.

Enums

ApprovalDecision

The user’s response to an ApprovalRequest.

ApprovalReason

Why a permission policy is requesting human approval before proceeding.

CollisionPolicy

Policy applied when the same tool name appears in more than one ToolSource of a BasicToolExecutor.

FileSystemPermissionRequest

Permission request for a filesystem operation.

McpPermissionRequest

Permission request for an MCP (Model Context Protocol) operation.

PermissionCode

Machine-readable code indicating why a permission was denied.

PermissionDecision

The verdict from a PermissionChecker for a single PermissionRequest.

PolicyMatch

The result of a single PermissionPolicy evaluation.

ToolError

Errors that can occur during tool lookup, permission checking, or execution.

ToolExecutionOutcome

The three-way result of a ToolExecutor::execute call.

ToolInterruption

A tool execution was paused because it needs external input.

ToolOutputOverflowAction

What the executor should do when a tool result exceeds its configured model-facing byte budget.

Constants

TOOL_OUTPUT_LIMIT_METADATA_KEY

Metadata key used by tool specs to advertise their preferred output overflow behaviour. Hosts can respect this through ConfigurableToolOutputTruncationStrategy, while still overriding individual tools in executor configuration.

TOOL_RESULT_READ_TOOL_NAME

Traits

PermissionChecker

Evaluates a PermissionRequest and returns a final PermissionDecision.

PermissionPolicy

A single, focused permission rule that contributes to a composite decision.

PermissionRequest

A description of an operation that requires permission before it can proceed.

Tool

The central abstraction for an executable tool in an agentkit agent.

ToolExecutor

Trait for executing tool calls with permission checking and interruption handling.

ToolOutputArtifactStore

ToolOutputTruncationStrategy

Strategy hook for enforcing model-facing tool-output budgets.

ToolResources

Trait for dependency injection into tool implementations.

ToolSource

Read-side contract for a federated tool catalog.

Functions

dynamic_catalog

Constructs a fresh dynamic tool catalog as a writer/reader pair.

tool_result_readback_registry

Convenience registry for safe tool-output readback.