Built-in tools reference

Overview

This inventory combines the meerkat-tools builtin dispatcher with the runtime-composed memory, comms, schedule, WorkGraph, mob, image-generation, and web-search surfaces. Each family remains the source of truth for its own tool names, schemas, execution contract, mutation class, and gates. In the table, Default means enabled inside an already-selected tool family. It does not mean a bare AgentFactory exposes that family. Product surfaces may apply explicit presets of their own.

Tool	Category	Default	Gate	Description
`task_create`	Task	Yes	—	Create a new task
`task_get`	Task	Yes	—	Get a task by ID
`task_list`	Task	Yes	—	List tasks with optional filters
`task_update`	Task	Yes	—	Update an existing task
`shell`	Shell	No	—	Execute a shell command
`shell_jobs`	Shell	No	—	List background shell jobs
`shell_job_status`	Shell	No	—	Check background job status
`shell_job_cancel`	Shell	No	—	Cancel a background job
`monitor_start`	Shell monitor	No	durable job + blob stores	Start a high-trust framed script monitor
`memory_search`	Memory	N/A	`memory-store-session`	Search semantic memory
`datetime`	Utility	Yes	—	Get current date/time
`apply_patch`	Utility	Yes	—	Apply structured file patches inside the project root
`view_image`	Utility	Yes	`image_tool_results`	Read an image file and return base64 content
`generate_image`	Image generation	Runtime-backed	image runtime dependencies; inherited in normal composite or explicitly enabled in minimal composition	Generate or edit assistant images and commit blob-backed image blocks
`web_search`	Web search fallback	Runtime-backed	provider search executor	Search through Meerkat when the active model has no native search tool
`blob_save_file`	Blob files	Runtime-backed	blob store	Save decoded blob bytes to a project-root-contained file
`blob_load_file`	Blob files	Runtime-backed	blob store	Load a project-root-contained file into the realm blob store
`blob_inspect`	Blob files	Runtime-backed	blob store	Inspect blob media type and decoded byte size without returning bytes
`send_message`	Comms	Yes	`comms`	Send a collaboration message to a peer
`reply_to_peer`	Comms	Yes	`comms`	Reply through the turn-scoped capability minted for an incoming peer message
`send_request`	Comms	Yes	`comms`	Send a structured request to a peer
`send_response`	Comms	Yes	`comms`	Send a response to a peer request
`peers`	Comms	Yes	`comms`	List discoverable peers (trusted + inproc)
`browse_skills`	Skills	No	`skills` + explicit tool policy	Browse skill collections and search skills
`load_skill`	Skills	No	`skills` + explicit tool policy	Load a skill’s full instructions into the conversation
`skill_list_resources`	Skills	No	`skills` + explicit tool policy	List skill-owned resources
`skill_read_resource`	Skills	No	`skills` + explicit tool policy	Read a specific skill-owned resource
`skill_invoke_function`	Skills	No	`skills` + explicit tool policy	Invoke a skill-defined function
`tool_catalog_search`	Control plane	Adaptive	exact deferred catalog	Search deferred tool-catalog entries
`tool_catalog_load`	Control plane	Adaptive	exact deferred catalog	Stage deferred tool-catalog entries for visibility
`brain_swap`	Model routing	Conditional	realization host + multiple reachable models + tool policy	Stage a model switch for a later input
`delegate`	Mob	Yes	`mob` + generated authority	Run one bounded helper task in an implicit mob
`fork_off`	Mob	Yes	`mob` + generated authority	Run a bounded task in a durable transcript-forked member
`council`	Mob	Yes	`mob` + generated authority	Convene a bounded temporary council forked from existing members
`conclude_objective`	Mob	Yes	`mob` + kickoff objective	Conclude the pre-addressed kickoff objective
`mob_create`	Mob	Yes	`mob` + generated authority	Create an explicit mob
`mob_destroy`	Mob	Yes	`mob` + mob scope	Destroy an explicit mob
`mob_spawn_member`	Mob	Yes	`mob` + spawn scope	Spawn a member
`mob_retire_member`	Mob	Yes	`mob` + mob scope	Retire a member and archive its session
`mob_check_member`	Mob	Yes	`mob` + mob scope	Read member execution status and output
`mob_list_members`	Mob	Yes	`mob` + mob scope	List a mob’s members
`mob_list`	Mob	Yes	`mob` + generated authority	List managed mobs
`mob_wire`	Mob	Yes	`mob` + mob scope	Wire a member to a local or external peer
`mob_unwire`	Mob	Yes	`mob` + mob scope	Remove a member wiring relationship
`mob_profile_create`	Mob profile	Conditional	realm profile store	Create a reusable realm profile
`mob_profile_get`	Mob profile	Conditional	realm profile store	Read a realm profile
`mob_profile_list`	Mob profile	Conditional	realm profile store	List realm profiles
`mob_profile_update`	Mob profile	Conditional	realm profile store	Update a realm profile by expected revision
`mob_profile_delete`	Mob profile	Conditional	realm profile store	Delete a realm profile by expected revision
`mob_profile_list_sources`	Mob profile	Conditional	profile store + snapshot provider	List visible tool sources for profile authoring
`meerkat_schedule_create`	Schedule	Yes	`schedule`	Create a new schedule
`meerkat_schedule_get`	Schedule	Yes	`schedule`	Read one schedule
`meerkat_schedule_list`	Schedule	Yes	`schedule`	List schedules
`meerkat_schedule_update`	Schedule	Yes	`schedule`	Update trigger, target, or policies
`meerkat_schedule_pause`	Schedule	Yes	`schedule`	Pause a schedule
`meerkat_schedule_resume`	Schedule	Yes	`schedule`	Resume a paused schedule
`meerkat_schedule_delete`	Schedule	Yes	`schedule`	Delete a schedule
`meerkat_schedule_occurrences`	Schedule	Yes	`schedule`	List occurrences for a schedule
`workgraph_create`	WorkGraph	No	`work_graph`	Create a work item
`workgraph_get`	WorkGraph	No	`work_graph`	Read one item
`workgraph_list`	WorkGraph	No	`work_graph`	List items
`workgraph_ready`	WorkGraph	No	`work_graph`	List ready items
`workgraph_snapshot`	WorkGraph	No	`work_graph`	Read an observability snapshot
`workgraph_events`	WorkGraph	No	`work_graph`	Read event history
`workgraph_claim`	WorkGraph	No	`work_graph`	Claim an item
`workgraph_release`	WorkGraph	No	`work_graph`	Release a claim
`workgraph_update`	WorkGraph	No	`work_graph`	Update item fields
`workgraph_block`	WorkGraph	No	`work_graph`	Mark an item blocked
`workgraph_close`	WorkGraph	No	`work_graph`	Close an item terminally
`workgraph_link`	WorkGraph	No	`work_graph`	Add an edge
`workgraph_add_evidence`	WorkGraph	No	`work_graph`	Add evidence
`workgraph_attention_reassign`	WorkGraph	No	`work_graph`	Reassign a WorkGraph attention binding
`workgraph_policy_escalate`	WorkGraph	No	`work_graph`	Monotonically tighten a WorkGraph completion policy

Enabling and disabling tools

Factory-level flags

AgentFactory controls which tool categories are available via builder methods:

Flag	Builder Method	Default	Controls
`enable_builtins`	`.builtins(bool)`	`false`	Task tools, utility tools (`datetime`, `apply_patch`, `view_image`), and blob file tools when a blob store is wired
`enable_shell`	`.shell(bool)`	`false`	Standard shell tools (`shell`, `shell_jobs`, `shell_job_status`, `shell_job_cancel`); `monitor_start` remains an explicit high-trust policy decision
`enable_memory`	`.memory(bool)`	`false`	`memory_search` (requires `memory-store-session` feature)
`enable_schedule`	`.schedule(bool)`	`false`	Scheduler tools (`meerkat_schedule_*`)
`enable_workgraph`	`.workgraph(bool)`	`false`	WorkGraph tools (`workgraph_*`)
`enable_comms`	`.comms(bool)`	`false`	All comms tools (requires `comms` feature)
`enable_mob`	`.mob(bool)`	`false`	Mob orchestration tools (`mob_`, `meerkat_`)

AgentFactory is the only place tool categories are composed. The public meerkat::AgentBuilder delegates to the factory path with explicit client/tool/store overrides. The lower-level meerkat_core::AgentBuilder is not re-exported by the facade and is not a public standalone embedding API. See AgentBuilder vs AgentFactory.Source: meerkat/src/factory.rs — AgentFactory struct and builder methods.

Per-build overrides

Each AgentBuildConfig can override factory-level flags for a single agent build:

Override Field	Type	Effect
`override_builtins`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_shell`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_memory`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_schedule`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_workgraph`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_mob`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_comms`	`ToolCategoryOverride`	Explicit `enable`, `disable`, or `inherit`
`override_image_generation`	`ToolCategoryOverride`	Controls assistant image-generation visibility independently from general builtins
`override_web_search`	`ToolCategoryOverride`	Controls provider-native search or the Meerkat fallback independently from general builtins

All default to inherit. The categories backed by factory flags inherit those flags. Image generation treats inherit as visible once its session-owned substrate is wired into the normal composite dispatcher. The minimal no-builtins/no-shell early return requires an explicit image enable to create that dispatcher. The Meerkat-owned web-search fallback is different: it treats inherit as hidden and requires an explicit enable. An explicit enable fails closed if its runtime dependencies cannot be provisioned. Enabling either category does not enable general builtins.Source: meerkat/src/factory.rs — AgentBuildConfig struct.

ToolPolicyLayer

Individual tools can be enabled or disabled via ToolPolicyLayer in BuiltinToolConfig, but policy can only select tools from a category that was actually composed. When shell is enabled, the factory applies a policy that activates the four standard shell tools (which have default_enabled: false). The high-trust monitor_start and all five skill tools also default off and require an explicit policy enable in a custom dispatcher build.

Execution contracts and mutation classes

Every dispatcher exposes a ToolExecutionContract per tool. The default is Fast; tools may additionally support Streaming or Detached. Streaming contracts own progress/cancellation policy. Detached contracts declare runner identity, submission idempotency, restart class, and a bounded submission deadline. The resolved deadline is the narrowest contribution in the call’s deadline chain.RestartClass values are Adoptable, CheckpointResumable, Replayable, and NonResumable. A tool can advertise only the classes its runner can honor.Separately, every dispatcher reports ToolMutationClass::ReadOnly, Mutating, or Unknown. Unknown is fail-closed uncertainty for third-party or undeclared tools, not an assertion that the call is harmless.

Capability registrations

Capabilities are registered via the inventory crate in meerkat-tools/src/lib.rs:

Builtins (CapabilityId::Builtins): task_list, task_create, task_get, task_update, datetime, apply_patch, view_image, and runtime-backed blob_save_file/blob_load_file/blob_inspect when a blob store is available. Controlled by config.tools.builtins_enabled.
Shell (CapabilityId::Shell): shell, shell_jobs, shell_job_status, shell_job_cancel, plus opt-in monitor_start. Controlled by config.tools.shell_enabled and per-tool policy.
Image generation: runtime-owned generate_image, controlled by override_image_generation after runtime capability resolution.
Web search: provider-native search when the active model owns it, otherwise the Meerkat-owned web_search fallback; controlled by override_web_search.
Schedule (CapabilityId::Schedule): meerkat_schedule_*. Controlled by config.tools.schedule_enabled.
WorkGraph (CapabilityId::WorkGraph): workgraph_*. Controlled by config.tools.workgraph_enabled.

Runtime tool scoping

Beyond static factory flags and per-build overrides, tool visibility can be changed at runtime during a live session. See Tool scoping for the conceptual overview.

ToolScope lifecycle

ToolScope (in meerkat-core) manages runtime tool visibility. It holds the base tool set from the dispatcher, an active external filter, and an optional per-turn overlay.Staging: External callers stage filter updates via ToolScopeHandle::stage_external_filter(filter). The staged filter is NOT applied immediately — the current turn is unaffected.Boundary apply: At the start of each CallingLlm loop iteration, tool_scope.apply_staged(dispatcher_tools) atomically promotes the staged filter to active, prunes stale tool names, and returns the visible tool set. A ToolConfigChanged event is emitted and a typed tool_config system notice is recorded in the conversation.Filter types:

ToolFilter::All — no restriction (default)
ToolFilter::Allow(set) — only listed tools are visible
ToolFilter::Deny(set) — listed tools are hidden

Composition: Most-restrictive wins. Multiple allow-lists intersect, multiple deny-lists union, deny beats allow.Persistence: The active external filter is stored in session metadata under tool_scope_external_filter and restored on session resume.Source: meerkat-core/src/tool_scope.rs

Live MCP server mutation

MCP servers can be added or removed from a running session. Operations are staged on the McpRouter and applied at the next turn boundary.

Surface	Method	Status
JSON-RPC	`mcp/add`, `mcp/remove`, `mcp/reload`	Fully wired (staged)
REST	`POST /sessions/{id}/mcp/add\|remove\|reload`	Fully wired
CLI	`rkat mcp add/remove/list/get`	Config surface; start or resume a session to load config
MCP server	`meerkat_mcp_add`, `meerkat_mcp_remove`, `meerkat_mcp_reload`	Fully wired

Servers being removed transition through Active → Removing (draining) → Removed to allow in-flight tool calls to complete before finalization.Source: meerkat-mcp/src/router.rs, meerkat-rpc/src/handlers/mcp.rs

Per-turn tool overlay

Mob flow steps can restrict tools for a single turn via TurnToolOverlay:

let overlay = TurnToolOverlay {
    allowed_tools: Some(vec!["shell".into()]),
    blocked_tools: Some(vec!["task_create".into()]),
    ..Default::default()
};

The native allow/deny fields are Option<Vec<ToolName>>; .into() converts the names above. The default supplies an empty host-only dispatch_context. Set the overlay on StartTurnRequest.runtime.turn_tool_overlay by the flow engine or another trusted per-turn producer. It is ephemeral — cleared after the turn completes — and composes with the external filter using most-restrictive semantics.Public wire requests use the caller-safe PublicTurnToolOverlay shape: allowed_tools and blocked_tools contain string names. They do not accept the internal dispatch_context field.Source: meerkat-core/src/service/mod.rs, meerkat-mob/src/runtime/flow.rs

Deferred tool catalog control plane

An exact dispatcher can keep eligible session tools out of the LLM’s inline schema set and expose two always-inline control tools instead. The adaptive selector enters deferred mode when a source is still pending, at least two eligible tools exist, or their combined name, description, and schema volume reaches 160 bytes. These tools are not part of the general builtins gate.

tool_catalog_search

Search deferred-eligible session tools without loading them.

String

Optional case-insensitive substring search over canonical name and description.

usize

default:"10"

Result limit, clamped to 1-50.

The response contains catalog_exact, total_matches, results, optional pending_sources, and optional empty_result_status. Each result reports name, description, currently_callable, and visibility_status: loaded, deferred, blocked_by_filter, or temporarily_unavailable. pending_source is used only as the empty-result status while a catalog source is pending.Source: meerkat-tools/src/control_plane.rs

tool_catalog_load

Stage one or more canonical deferred tool names for the next tool boundary. The control plane consults the bound ToolScope and fails closed when it has no authoritative visibility state.

String[]

required

One or more canonical tool names.

The response contains catalog_exact, accepted_names, noop_names, and one resolution per requested name. Rejection reasons are unknown_key, not_deferred_eligible, not_filterable, or temporarily_unavailable. Already staged or visible names are successful no-ops. Accepted loads take effect at the next boundary, not during the current tool call.Source: meerkat-tools/src/control_plane.rs, meerkat-core/src/tool_catalog.rs

Model-switch tool

brain_swap is available only when the host can realize committed model handoffs, more than one distinct model is reachable, and tool policy permits it. Its required target_model argument selects from that reachable set. The tool returns staged or already_staged; it does not change the model during the current run. A clean run completion commits the request, which the runtime attempts to realize before processing the next input. Failed, interrupted, or hook-denied runs do not commit the switch, and later realization can still be denied or held. A staging result is not proof that the model has changed. Source: meerkat-tools/src/builtin/brain_swap.rs, meerkat-tools/src/builtin/composite.rs, meerkat-core/src/agent/state.rs, meerkat-runtime/src/service_ext.rs

Mob tools

AgentMobToolSurface is composed only for sessions with generated MobMachine authority. It defines the 13 core tools in the inventory above, including fork_off for durable transcript-forked work and council for bounded discussion among temporary forks of existing members. Realm profile storage adds five profile CRUD tools; a parent-owned snapshot provider also adds mob_profile_list_sources. Admission is then checked again at each dispatch against the current typed mob, spawn, profile-mutation, or objective scope. See Mob tools for argument shapes and workflows. Host/operator surfaces for placement, binding, grants, observation, live member sessions, and hard cancellation are control-plane APIs, not agent builtins, so they are intentionally excluded from this inventory. Source: meerkat-mob-mcp/src/agent_tools.rs

Schedule tools

Schedule tools are the agent-facing scheduler surface. They are distinct from the host APIs (schedule/* over RPC and /schedules/* over REST).

Schedule tool inventory

Tool	Purpose
`meerkat_schedule_create`	Create a durable schedule with trigger, target, and policies
`meerkat_schedule_get`	Read one schedule by `schedule_id`
`meerkat_schedule_list`	List schedules in the active realm
`meerkat_schedule_update`	Update trigger, target, policies, or labels
`meerkat_schedule_pause`	Pause a schedule
`meerkat_schedule_resume`	Resume a paused schedule
`meerkat_schedule_delete`	Delete a schedule
`meerkat_schedule_occurrences`	List occurrences for a schedule

These tools are provided by ScheduleToolDispatcher in meerkat-schedule and are gated by the scheduler capability.

WorkGraph tools

WorkGraph tools are the agent-facing write path for durable work. Host RPC, REST, and CLI expose observability; CLI and trusted hosts add narrow goal and attention controls.

WorkGraph tool inventory

Tool	Purpose
`workgraph_create`	Create a durable work item
`workgraph_get`	Read one item
`workgraph_list`	List items with filters
`workgraph_ready`	List machine-derived ready items
`workgraph_snapshot`	Read items, edges, ready ids, timestamp, and event high-water mark
`workgraph_events`	Read event history
`workgraph_claim`	Claim an item with expected revision and typed owner
`workgraph_release`	Release an active claim
`workgraph_update`	Update mutable fields
`workgraph_block`	Mark an item blocked
`workgraph_close`	Close as `completed`, `cancelled`, or `failed`
`workgraph_link`	Add an edge
`workgraph_add_evidence`	Add an evidence reference
`workgraph_attention_reassign`	Reassign an attention binding with a current authority projection
`workgraph_policy_escalate`	Monotonically tighten an item’s completion policy

For operating guidance, load the workgraph-workflow companion skill when it is available. For the data model and host observability surfaces, see WorkGraph reference.

Task tools

Task tools provide structured work tracking. They are enabled by default when builtins are on. With the session-store feature, factory-built sessions use a session-scoped SqliteTaskStore, so resume restores the same task set. Builds without that feature use FileTaskStore when a project root exists and MemoryTaskStore otherwise.

Task data model

A Task object returned by task tools has these fields:

Field	Type	Description
`id`	`String`	Unique task identifier
`subject`	`String`	Short subject/title
`description`	`String`	Detailed description
`status`	`String`	`"pending"`, `"in_progress"`, or `"completed"`
`priority`	`String`	`"low"`, `"medium"`, or `"high"`
`labels`	`String[]`	Labels/tags for categorization
`blocks`	`String[]`	IDs of tasks that this task blocks
`blocked_by`	`String[]`	IDs of tasks that block this task
`created_at`	`String`	ISO 8601 creation timestamp
`updated_at`	`String`	ISO 8601 last-updated timestamp
`created_by_session`	`String?`	Session ID that created this task
`updated_by_session`	`String?`	Session ID that last updated this task
`owner`	`String?`	Owner/assignee (agent name or user identifier)
`metadata`	`Object`	Arbitrary key-value metadata

Source: meerkat-tools/src/builtin/types.rs — Task struct.

task_create

Create a new task in the project task list.Default enabled: Yes

String

required

Short subject/title of the task.

String

required

Detailed description of what needs to be done.

String

default:"medium"

"low", "medium", or "high".

String[]

default:"[]"

Labels/tags for categorization.

String[]

default:"[]"

Task IDs that this task blocks.

String[]

default:"[]"

Task IDs that block this task.

String

default:"null"

Owner/assignee.

Object

default:"{}"

Arbitrary key-value metadata.

Returns: The created Task object (see task data model above).Source: meerkat-tools/src/builtin/tasks/task_create.rs

task_get

Get a task by its ID.Default enabled: Yes

String

required

The task ID to retrieve.

Returns: The Task object matching the given ID.Error: ExecutionFailed if the task ID is not found.Source: meerkat-tools/src/builtin/tasks/task_get.rs

task_list

List tasks in the project, optionally filtered by status or labels.Default enabled: Yes

String

default:"null (all)"

Filter by status: "pending", "in_progress", or "completed".

String[]

default:"null (all)"

Filter by labels (tasks matching any label).

Returns: Array of Task objects matching the filters.Source: meerkat-tools/src/builtin/tasks/task_list.rs

task_update

Update an existing task. Only provided fields are modified; omitted fields remain unchanged.Default enabled: Yes

String

required

The task ID to update.

String

default:"unchanged"

New subject/title.

String

default:"unchanged"

New description.

String

default:"unchanged"

New status: "pending", "in_progress", or "completed".

String

default:"unchanged"

New priority: "low", "medium", or "high".

String[]

default:"unchanged"

Replace all labels.

String

default:"unchanged"

New owner/assignee.

Object

default:"unchanged"

Merge metadata (set key to null to remove).

String[]

default:"[]"

Task IDs to add to the blocks list.

String[]

default:"[]"

Task IDs to remove from the blocks list.

String[]

default:"[]"

Task IDs to add to the blocked_by list.

String[]

default:"[]"

Task IDs to remove from the blocked_by list.

Returns: The updated Task object.Error: ExecutionFailed if the task ID is not found.Source: meerkat-tools/src/builtin/tasks/task_update.rs

Shell tools

Shell tools execute commands and manage background jobs. They are all default_enabled: false. The effective shell category must first be composed; the factory then uses ToolPolicyLayer to activate the four standard shell tools. A policy cannot create an absent shell category, and monitor_start still requires its own explicit policy enable.

background: true is available only when the session has a persistent realm job store and blob store. Submission, status, result references, cancellation, and terminal delivery are durable. The shell worker itself is non_resumable: if its process is lost across restart, the committed attempt becomes worker_lost after its existing lease expires and is never silently replayed.

command: "some-command &" and background: true are different contracts. An ampersand is only syntax interpreted by the selected shell. Meerkat still executes that shell invocation through the foreground tool path, returns the ordinary foreground result, and does not create a job ID or a record visible to shell_jobs, shell_job_status, or shell_job_cancel. Any child the shell leaves running is unmanaged and its lifetime is not guaranteed. Use background: true when the command must be managed as a Meerkat shell job. It commits and returns a stable job ID and enables durable status/list/cancel operations. This does not claim that the subprocess survives a host restart: the durable record survives and reports the non-resumable worker loss.

Timeout hierarchy

Tool execution has layered deadlines; the narrowest applicable layer wins.

Layer	Default/current contract	Meaning
Foreground shell command	30 seconds	Shell-internal command deadline
SDK/builder `ToolDispatcher`	30 seconds	Enforced dispatcher-layer deadline when this wrapper is composed
Schedule occurrence lease	60 seconds	Scheduling/redelivery ownership lease; not a long-job execution deadline
Normal Meerkat tool batch	600 seconds	Agent-loop outer deadline; per-tool overrides may narrow it
MobKit provider callback	120 seconds	Public host-callback work window
MobKit Python/TypeScript callback cancellation	125 seconds	Host cancellation margin, not extra work time
MobKit gateway callback wire	130 seconds	Transport margin, not extra work time
LLM stream inactivity	300 seconds	Provider-stream watchdog; unrelated to tool callbacks

Changing the normal Meerkat tool timeout cannot extend a narrower shell, SDK/builder ToolDispatcher, or MobKit callback deadline. The foreground shell and dispatcher deadlines are distinct enforced layers, even though both defaults currently come from ToolTimeoutPolicy. Background shell submission returns within the normal tool call, but the spawned command keeps its own shell timeout. The command runs under one fenced non-resumable attempt; terminal state is committed before runtime notification delivery.

Shell configuration

Shell behavior is controlled by ShellConfig:

Config Field	Type	Default	Description
`enabled`	`bool`	`false`	Master switch for shell tools
`default_timeout_secs`	`u64`	`30`	Default command timeout
`restrict_to_project`	`bool`	`true`	Restrict working dirs to project root
`shell`	`String`	`"nu"`	Shell binary name (Nushell by default; falls back to bash/zsh/sh)
`shell_path`	`PathBuf?`	`None`	Explicit shell binary path
`project_root`	`PathBuf`	CWD	Project root for path restriction
`max_completed_jobs`	`usize`	`100`	Accepted legacy compatibility field; the durable job runtime does not currently use it as retention authority.
`completed_job_ttl_secs`	`u64`	`300`	Accepted legacy compatibility field; the durable job runtime does not currently expire records from this value.
`max_concurrent_processes`	`usize`	`10`	Maximum concurrent background processes
`security_mode`	`SecurityMode`	`Unrestricted`	Command security policy
`security_patterns`	`Vec<String>`	`[]`	Glob patterns for allow/deny lists

Source: meerkat-tools/src/builtin/shell/config.rs

Shell security modes

The SecurityEngine validates commands before execution using POSIX-compliant word splitting (shlex) and glob pattern matching (globset).

Mode	Behavior
`Unrestricted`	All commands allowed (default)
`AllowList`	Only commands matching `security_patterns` globs are allowed
`DenyList`	Commands matching `security_patterns` globs are rejected

The engine parses the command into an executable and arguments, canonicalizes that complete invocation, and matches the full canonical string against the pattern set.Source: meerkat-tools/src/builtin/shell/security.rs

shell

Execute a shell command. Uses POSIX-style parsing for policy checks; runs via Nushell or fallback shell.Default enabled: No (requires shell to be enabled)

String

required

The command to execute (POSIX-style parsing for policy checks).

String

default:"Project root"

Working directory (relative to project root).

u64

default:"Config default (30)"

Timeout in seconds.

bool

default:"false"

If true, durably submit a non-resumable shell job and return its stable job ID. Requires persistent realm job and blob stores. Job truth survives restart; a lost subprocess is classified as worker_lost, not replayed.

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "timed_out": false,
  "duration_secs": 1.23
}

{
  "job_id": "job_<uuid-v7>",
  "status": "queued",
  "restart_class": "non_resumable",
  "awaitable": true,
  "message": "Durable shell job submitted with ID: job_<uuid-v7>"
}

Output is truncated to the last 100,000 characters if it exceeds that limit. Fields stdout_lossy and stderr_lossy indicate whether output was lossy-decoded from non-UTF-8 bytes.

Source: meerkat-tools/src/builtin/shell/tool.rs

monitor_start

Start an explicitly enabled, high-trust durable script monitor. Unlike an ordinary background shell command, the monitor consumes a typed output protocol and can publish notifications, checkpoints, progress, and completion. Notifications do not complete the job.Default enabled: No. enable_shell alone does not grant this high-trust tool; an embedding surface must enable it through tool policy. Persistent realm job and blob stores are required.

Field	Default	Meaning
`command`	required	Script or command to run.
`working_dir`	project root	Validated working directory.
`timeout_secs`	shell default	Command lifetime; must be greater than zero.
`protocol`	`framed_jsonl`	`framed_jsonl` or plain `lines`.
`restart_class`	`non_resumable`	`replayable`, `checkpoint_resumable`, or `non_resumable`.
`delivery`	`notification`	`record`, `notification`, `event_steer`, or `event_queue`.
`max_line_bytes`	`65536`	Maximum bytes in one protocol line.
`max_notifications_per_window`	`60`	Notification rate limit.
`notification_window_ms`	`60000`	Rate-limit window.
`max_retained_diagnostic_bytes`	`262144`	Retained non-frame diagnostics cap.

{
  "job_id": "job_<uuid-v7>",
  "status": "running",
  "restart_class": "checkpoint_resumable",
  "output_protocol": "framed_jsonl",
  "delivery": "notification",
  "message": "Durable monitor submitted with ID: job_<uuid-v7>"
}

Restart class is a declaration enforced by the detached execution contract, not a promise inferred from the command text. Replayable and resumable scripts must implement the corresponding idempotency/checkpoint behavior.Source: meerkat-tools/src/builtin/shell/monitor_tool.rs

shell_jobs

List all background shell jobs.Default enabled: No (requires shell to be enabled)Parameters: None (empty object).

[
  {
    "id": "job_<uuid-v7>",
    "command": "echo hello",
    "status": "running",
    "started_at_unix": 1700000000
  }
]

The summary status field is one of: "queued", "running", "completed", "failed", "cancelled", "worker_lost", or "needs_attention".Source: meerkat-tools/src/builtin/shell/jobs_list_tool.rs

shell_job_status

Check status of a background shell job. Returns full job details including output when complete.Default enabled: No (requires shell to be enabled)

String

required

The job ID to check.

{
  "id": "job_<uuid-v7>",
  "command": "echo test",
  "working_dir": "/path/to/project",
  "timeout_secs": 30,
  "started_at_unix": 1700000000,
  "status": {
    "status": "completed",
    "exit_code": 0,
    "stdout": "test\n",
    "stderr": "",
    "duration_secs": 0.01
  }
}

Error: ExecutionFailed if the job ID is not found.Source: meerkat-tools/src/builtin/shell/job_status_tool.rs

shell_job_cancel

Request cancellation of a running background shell job. For a live process, success returns cancellation_requested; this is not a terminal acknowledgement. Poll shell_job_status until it reports cancelled. Meerkat publishes terminal cancelled status only after the worker proves the complete process group has been contained. Synthetic jobs with no live process may return cancelled immediately because there is nothing to contain.Default enabled: No (requires shell to be enabled)

String

required

The job ID to cancel.

{
  "job_id": "job_<uuid-v7>",
  "status": "cancellation_requested"
}

Error: ExecutionFailed if the job ID is not found.Source: meerkat-tools/src/builtin/shell/job_cancel_tool.rs

Shell types

JobId format: "job_" followed by a UUID v7 string.JobStatus variants: Queued, Running, Completed, Failed, Cancelled, WorkerLost, and NeedsAttention (serialized as lowercase snake_case status tags). A command timeout is represented by the worker’s terminal failure facts; there is no current TimedOut enum variant.Source: meerkat-tools/src/builtin/shell/types.rs

Memory tool

The memory search tool lives in the meerkat-memory crate and is composed into the tool dispatcher as a separate MemorySearchDispatcher (implementing AgentToolDispatcher). It is NOT part of CompositeDispatcher — it is wired via ToolGateway when the memory-store-session feature is enabled and enable_memory is true.

memory_search

Search semantic memory for past conversation content. Memory contains text from earlier turns in the current session that were compacted away to save context space.

String

required

Natural language search query describing what you want to recall.

usize

default:"5"

Maximum number of results to return (max: 20).

The limit is capped at 20 regardless of the requested value.

[
  {
    "content": "The project codename is AURORA-7",
    "score": 0.87,
    "source_range": { "start": 3, "end": 4 }
  }
]

source_range is the half-open [start, end) offset range of the source message(s) the entry was indexed from. Memory is scoped to a single session; results do not carry a session_id, and there is no cross-session recall.Returns an empty array if no matches are found.Source: meerkat-memory/src/tool.rs

Utility tools

Utility tools are general-purpose helpers enabled by default when builtins are on.

datetime

Get the current date and time. Returns ISO 8601 formatted datetime and Unix timestamp.Default enabled: YesParameters: None (empty object).

{
  "iso8601": "2025-01-15T14:30:00+00:00",
  "date": "2025-01-15",
  "time": "14:30:00",
  "timezone": "UTC",
  "unix_timestamp": 1736951400,
  "year": "2025",
  "month": "01",
  "day": "15",
  "weekday": "Wednesday"
}

Source: meerkat-tools/src/builtin/utility/datetime.rs

apply_patch

Apply a line-oriented patch that can add, update, move with edits, or delete files inside the project root. This tool is classified Mutating.

String

required

Patch text wrapped by *** Begin Patch and *** End Patch. File operations use *** Add File:, *** Update File:, optional *** Move to:, and *** Delete File: markers. Update hunks use literal @@ context plus space, -, and + line prefixes.

Paths must be project-root-relative. Lexical and symlink escapes are rejected. A pure rename is not supported: a move must include at least one update hunk. Multi-file patches are applied in order and are not transactional, so an error after an earlier operation can leave that earlier operation applied.The JSON result reports status: "success" plus added_files, modified_files, and deleted_files.Source: meerkat-tools/src/builtin/utility/apply_patch.rs

view_image

Read an image file from the project directory and return its contents as a base64-encoded ContentBlock::Image. This enables vision-capable models to analyze images from disk during tool use.Default enabled: Yes (when builtins are on and the model supports image tool results)

String

required

Path to the image file, relative to the project root.

Supported formats: PNG, JPEG, GIF, WebP, SVG.Size limit: 5 MB. Files exceeding this limit return an error.Capability gating: view_image is currently hidden via ToolScope when the active model does not support image content in tool results (ModelProfile.image_tool_results == false).Returns: A content-block result containing a single ContentBlock::Image with the base64-encoded image data and detected media type.Source: meerkat-tools/src/builtin/utility/view_image.rs

blob_save_file

Save decoded bytes from the session blob store to a file inside the project root. This is the model-facing equivalent of materializing a blob with rkat blob get, but it remains sandboxed to the active project.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.

String

required

Blob ID to save.

String

required

Destination path, relative to the project root or absolute within the project root.

Boolean

default:"false"

Whether to replace an existing file.

Returns: JSON metadata: blob_id, media_type, path, and bytes_written. Raw bytes are never returned in the tool result.Source: meerkat-tools/src/builtin/utility/blob_file.rs

blob_load_file

Read a file inside the project root and store its bytes in the realm blob store.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.

String

required

Source path, relative to the project root or absolute within the project root.

String

default:"inferred from extension"

Optional media type. When omitted, Meerkat infers common image, text, JSON, CSV, SVG, and PDF media types from the file extension.

Size limit: 25 MB.Returns: JSON metadata: blob_id, media_type, path, and bytes_read. Raw bytes are never returned in the tool result.Source: meerkat-tools/src/builtin/utility/blob_file.rs

blob_inspect

Inspect a blob without returning its raw payload.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.

String

required

Blob ID to inspect.

Returns: JSON metadata: blob_id, media_type, and decoded size_bytes.Source: meerkat-tools/src/builtin/utility/blob_file.rs

generate_image

Generate or edit an assistant-owned image through the session image-generation substrate. Generated bytes are committed to the realm blob store and returned as durable AssistantImageRef values.Tool policy default: Yes after the category has been composed. Factory category default: Inherit, which is visible in the normal composite when the image-generation machine, executor, planner, session identity, and blob store are wired. A minimal no-builtins/no-shell composition needs explicit Enable; Mob profiles and in-process builds can use that override without opening general builtins. See the guide for the current surface matrix.

Object

required

Image generation request. The simple shape supports intent, prompt, instruction, source_images, reference_images, size, quality, format, count/n, target, provider, model, and provider_params.

Common request:

{
  "request": {
    "intent": "generate",
    "prompt": "a cozy tabby cat by a sunlit window",
    "size": "1024x1024",
    "quality": "auto",
    "format": "png",
    "count": 1,
    "provider": "openai"
  }
}

Targets: auto uses the current provider’s image profile when available. Use provider: "openai" or provider: "gemini" to force a provider default. Use provider plus model to force a provider-owned image model.Supported universal options: size accepts auto, 1024x1024, 1024x1536, 1536x1024, or WIDTHxHEIGHT; quality accepts auto, low, medium, high; format accepts auto, png, jpeg, jpg, webp; count is currently limited to 1.Provider params: Use top-level size, quality, format, and intent for normal requests; these are Meerkat fields, not raw provider params. For the current gpt-image-2 default, OpenAI provider_params should normally be limited to background, output_compression, moderation, hosted-tool-only action, hosted-tool-only reasoning_effort, and hosted-tool-only web_search; background is auto or opaque only, output_compression applies when format is jpeg/webp, moderation is auto or low, action is usually omitted in favor of top-level intent, and input_fidelity is not accepted by Meerkat. Gemini accepts aspect_ratio and image_size.Returns: ImageGenerationToolResult JSON containing operation_id, terminal, images, provider_text, revised_prompt, native_metadata, and warnings. Each generated image includes blob_ref.blob_id, which can be saved from inside the session with blob_save_file or fetched externally with rkat blob get <blob_id> --output image.png.Source: meerkat-tools/src/builtin/image_generation.rsSee Image generation for provider behavior, examples, and troubleshooting.

Web search fallback tool

The active model may receive provider-native web search directly in its provider request. When the active model lacks native search and web search is explicitly enabled, AgentFactory can instead compose the Meerkat-owned web_search fallback against a configured OpenAI, Gemini, or Anthropic search executor. The explicit enable fails closed if no executor can be provisioned.

web_search

String

required

Non-empty natural-language search or research query.

String

Optional assertion: openai, gemini, or anthropic. When present it must match the fallback provider selected for the session.

String

Optional brief conversation context used to disambiguate the query.

The result is WebSearchResult: status, query, optional provider and model, optional answer, typed evidence, provider-observed native_events, optional error, and checked_at. Native events are evidence from the provider, not Meerkat-owned truth.This tool is classified read-only. Visibility is controlled by override_web_search, independently from general builtins.Source: meerkat-tools/src/builtin/web_search.rs

Comms tools

Comms tools enable inter-agent communication. They require the comms Cargo feature (dep:meerkat-comms) and the factory-level enable_comms flag. Unlike other tool categories, comms tools are provided as a separate CommsToolSurface dispatcher (implementing AgentToolDispatcher) and composed via DynamicToolComposite, NOT bundled into CompositeDispatcher. Tool availability is reported per tool through the catalog (comms_tool_unavailable_reason): send_message, reply_to_peer, and peers are advertised even before any peers are configured, while send_request and send_response require a runtime-bound command authority and are otherwise marked unavailable with the typed reason RuntimeCommandAuthorityUnavailable. Tool definitions (name, description, input schema) are dynamically loaded from meerkat_comms::tools_list().

send_message

Send a fire-and-forget collaboration message to a trusted peer.Default enabled: Yes (when comms is active)

String

required

Canonical peer ID from the peers tool.

String

Optional display name, retained only for diagnostics.

String

required

Message content.

Array

Optional multimodal blocks: text entries or image_ref entries (source: "current_turn" with index, or source: "blob" with blob_id and media_type).

String

required

Use "queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.

{ "status": "sent", "kind": "peer_message", "receipt": { ... } }

Source: meerkat-comms/src/mcp/tools.rs

reply_to_peer

Reply to the peer message that triggered the current turn. This tool is pre-addressed by a turn-scoped reply capability, so it deliberately has no peer_id argument.Default enabled: Yes when comms is active. It does not require runtime request/response command authority.

String

required

Reply text.

Array

Optional multimodal text or image_ref blocks.

String

required

queue for ordinary delivery or steer for urgent immediate processing.

String

Delivery ID selector. Omit when exactly one peer message triggered the turn. When several arrived, retry with one ID listed by ambiguous_reply.

{
  "body": "Acknowledged. The migration is complete.",
  "handling_mode": "queue"
}

Typed failures include no_reply_capability, ambiguous_reply, and unknown_reply_to. Trust is revalidated at dispatch time, so revoking a peer after turn admission invalidates the previously minted reply capability.Source: meerkat-comms/src/mcp/tools.rs

send_request

Send a structured request to a trusted peer. Use when you want explicit intent + params and a correlated response via send_response. Requires a runtime-bound command authority.Default enabled: Yes (when comms is active and runtime command authority is attached)

String

required

Canonical peer ID from the peers tool.

String

Optional display name, retained only for diagnostics.

String

required

Typed request intent: "checksum_token" or "supervisor.bridge". Unknown intents fail at the serde boundary.

Object

required

Request parameters, validated against the selected intent.

Array

Optional multimodal blocks (text and image_ref entries).

String

required

Use "queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.

Use send_message for normal agent collaboration. Use send_request only when you want an explicit structured ask and later send_response correlated by in_reply_to.

{ "status": "sent", "kind": "peer_request", "receipt": { ... } }

Source: meerkat-comms/src/mcp/tools.rs

send_response

Send a response to a previously received request from a trusted peer. Requires a runtime-bound command authority.Default enabled: Yes (when comms is active and runtime command authority is attached)

String

required

Canonical peer ID from the peers tool.

String

Optional display name, retained only for diagnostics.

String (UUID)

required

ID of the request being responded to.

String

required

Response status: "accepted", "completed", or "failed".

Object

default:"null"

Typed response payload, validated against the original request contract.

Array

Optional multimodal blocks (text and image_ref entries).

String

Optional override for terminal responses: "queue" or "steer". Forbidden on "accepted" progress responses.

{ "status": "sent", "kind": "peer_response", "receipt": { ... } }

Source: meerkat-comms/src/mcp/tools.rs

peers

List all visible peers with connection info and optional metadata.Returns the runtime peer directory when runtime authority is attached, or a typed view of the trust store otherwise. The current agent is excluded. Names are display labels and may not be unique; use peer_id for sends.Default enabled: Yes (when comms is active)Parameters: None (empty object).

{
  "peers": [
    {
      "name": "agent-beta",
      "peer_id": "0193a1b2-...",
      "address": {
        "transport": "tcp",
        "endpoint": "127.0.0.1:4200"
      },
      "source": "trusted",
      "sendable_kinds": ["peer_message"],
      "capabilities": {
        "version": 1,
        "extensions": {}
      },
      "meta": {}
    }
  ]
}

Source: meerkat-comms/src/mcp/tools.rs — PeersInput

Skill tools

The five skill tools are registered only when a SkillRuntime is present. Each has default_enabled: false, so an embedding that constructs the builtin dispatcher must explicitly enable the desired names in BuiltinToolConfig. Current factory-built CLI, REST, and JSON-RPC sessions register the set but do not add that policy enable; preload and typed skill_refs still work, but the interactive skill tools are not advertised there. Every skill identity is a typed pair of source_uuid and skill_name. The runtime canonicalizes source-lineage remaps before reading or invoking it.

browse_skills and load_skill

browse_skills accepts optional query and source_uuid filters and returns active skills as {source_uuid, skill_name, name, description} entries.load_skill requires source_uuid and skill_name. It resolves and renders the skill, returning the canonical identity, display name, rendered body, and byte_size.Source: meerkat-tools/src/builtin/skills/browse.rs, meerkat-tools/src/builtin/skills/load.rs

Skill resources and functions

skill_list_resources takes source_uuid and skill_name and returns the skill’s artifact descriptors. skill_read_resource adds a required path and returns that artifact’s content.skill_invoke_function takes source_uuid, skill_name, function_name, and optional JSON-object arguments. Its success response echoes the canonical identity and function name and carries the skill function’s wire-opaque JSON in output.Source: meerkat-tools/src/builtin/skills/resources.rs, meerkat-tools/src/builtin/skills/functions.rs

Cargo feature gates

Tool availability depends on compile-time features in the meerkat-tools crate:

Feature	Default	Dependencies	Tools unlocked
`comms`	Yes	`dep:meerkat-comms`	`send_message`, `reply_to_peer`, `send_request`, `send_response`, `peers`
`mcp`	Yes	`dep:meerkat-mcp`	External MCP tool routing (not builtin tools)
`skills`	Yes	skill runtime types	The five policy-opt-in skill tool implementations

The memory_search tool is gated by the memory-store-session feature on the meerkat facade crate (not meerkat-tools), since MemorySearchDispatcher lives in meerkat-memory. Source: meerkat-tools/Cargo.toml

Reference

Architecture

Historical Implementation Records

Operations

Built-in tools reference

Overview

Enabling and disabling tools

Runtime tool scoping

Deferred tool catalog control plane

Model-switch tool

Mob tools

Schedule tools

WorkGraph tools

Task tools

Shell tools

Timeout hierarchy

Memory tool

Utility tools

Web search fallback tool

Comms tools

Skill tools

Cargo feature gates

​Overview

​Enabling and disabling tools

​Runtime tool scoping

​Deferred tool catalog control plane

​Model-switch tool

​Mob tools

​Schedule tools

​WorkGraph tools

​Task tools

​Shell tools

​Timeout hierarchy

​Memory tool

​Utility tools

​Web search fallback tool

​Comms tools

​Skill tools

​Cargo feature gates

Overview

Enabling and disabling tools

Runtime tool scoping

Deferred tool catalog control plane

Model-switch tool

Mob tools

Schedule tools

WorkGraph tools

Task tools

Shell tools

Timeout hierarchy

Memory tool

Utility tools

Web search fallback tool

Comms tools

Skill tools

Cargo feature gates