Module tools 

Structured read-only filesystem tools.

The model sees typed tools, not raw shell command strings. All subprocess invocations use std::process::Command argv arrays — never shell strings.

Safety Rules

• Workspace-root containment enforced after path normalization.
• Ignore rules respected and hidden files skipped by default.
• Hidden files, ignored files, symlink following, and unrestricted searches are opt-in only.
• Timeout, result-count, stdout/stderr byte, and line-length caps enforced.
• rg exit code 1 is treated as “no matches”, not an error.
• Arbitrary sed/awk, sed -i, and awk system() are not exposed; only typed read-only sawk inspection actions are available.

Modules

shell

Shell/process manager.

Structs

AgentRunConfig

Configuration for an agent run, shared by the fake and Umans providers.

SearchMatch

A single search match from rg --json.

ToolDefinition

A tool definition exposed to a provider/model.

ToolDisplayProjection

User-facing bounded projection of a tool result.

ToolEvidenceMetadata

Bounded, provider-neutral metadata about durable tool evidence.

ToolIterationBudget

Bounded tool-batch budget for one agent turn.

ToolModelProjection

Model-facing bounded projection of a tool result.

ToolOutput

Structured output returned by an application-owned tool executor.

ToolUseRequest

A tool-use request from a provider.

WriteResult

Structured result of a file write operation.

Enums

ProviderSchemaFormat

Provider-specific schema shape for model-visible tool definitions.

ToolBudgetDecision

Decision returned by ToolIterationBudget before a provider request.

ToolEvidenceKind

The kind of bounded evidence associated with a tool execution.

WriteOp

The kind of write operation performed on a file.

Constants

MAX_LINE_LEN

Maximum line length before truncation in tool output.

MAX_OUTPUT_BYTES

Maximum stdout/stderr bytes captured from a subprocess.

MAX_RESULTS

Default maximum number of results from a search or list operation.

MAX_TOOL_CONTINUATIONS

Maximum number of automatic tool-budget continuations per user turn.

MAX_TOOL_ITERATIONS

Maximum number of tool-call iterations per agent turn before the loop stops with a cap-exceeded error.

TIMEOUT_SECS

Timeout in seconds for subprocess execution.

Functions

dispatch_full

Dispatch a provider tool-use request, returning the tool output, an optional file-write result, and an optional shell-execution result.

dispatch_full_with_cancel_and_search

Dispatch a request with cancellation and the active search backend.

dispatch_full_with_cancel_and_search_and_registry

Dispatch a request with cancellation, search settings, and an optional application-owned background-process registry.

dispatch_full_with_search

Dispatch a provider tool-use request with the active search backend.

dispatch_runtime_full

Dispatch through MCP first when a namespaced MCP tool is available.

dispatch_runtime_full_with_cancel_and_search

Dispatch through MCP or built-ins with cancellation and search settings.

dispatch_runtime_full_with_cancel_and_search_and_registry

Dispatch through MCP or built-ins with cancellation, search settings, and an optional application-owned background-process registry.

dispatch_runtime_full_with_search

Dispatch through MCP or built-ins with the active search backend.

hash_content

Compute a stable hash of content using the standard library hasher.

provider_tool_catalog_schemas

Convert the tool catalog into provider-compatible tool schemas.

resolve_workspace_path

Resolve a workspace path using the same containment and symlink checks as tools.

runtime_tool_definitions

Return built-in tools plus cached MCP tools for a run.

searchable_file_paths

Return searchable file paths for UI features that need file selection.

sorted_json_value

Return a recursively sorted JSON value for deterministic debug rendering.

tool_catalog_schemas

Convert the tool catalog into Anthropic-compatible tool schemas.

tool_definitions

The catalog of tools exposed to the model.