Overview
This inventory combines themeerkat-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.
Enabling and disabling tools
Factory-level flags
Factory-level flags
AgentFactory controls which tool categories are available via builder methods: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: crates/meerkat/src/factory.rs — AgentFactory struct and builder methods.Per-build overrides
Per-build overrides
AgentBuildConfig can override factory-level flags for a single agent build: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: crates/meerkat/src/factory.rs — AgentBuildConfig struct.ToolPolicyLayer
ToolPolicyLayer
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
Execution contracts and mutation classes
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
Capability registrations
inventory crate in crates/meerkat-tools/src/lib.rs:- Builtins (
CapabilityId::Builtins):task_list,task_create,task_get,task_update,datetime,apply_patch,view_image, and runtime-backedblob_save_file/blob_load_file/blob_inspectwhen a blob store is available. Controlled byconfig.tools.builtins_enabled. - Shell (
CapabilityId::Shell):shell,shell_jobs,shell_job_status,shell_job_cancel, plus opt-inmonitor_start. Controlled byconfig.tools.shell_enabledand per-tool policy. - Image generation: runtime-owned
generate_image, controlled byoverride_image_generationafter runtime capability resolution. - Web search: provider-native search when the active model owns it, otherwise the Meerkat-owned
web_searchfallback; controlled byoverride_web_search. - Schedule (
CapabilityId::Schedule):meerkat_schedule_*. Controlled byconfig.tools.schedule_enabled. - WorkGraph (
CapabilityId::WorkGraph):workgraph_*. Controlled byconfig.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 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 visibleToolFilter::Deny(set)— listed tools are hidden
tool_scope_external_filter and restored on session resume.Source: crates/meerkat-core/src/tool_scope.rsLive MCP server mutation
Live MCP server mutation
McpRouter and applied at the next turn boundary.Active → Removing (draining) → Removed to allow in-flight tool calls to complete before finalization.Source: crates/meerkat-mcp/src/router.rs, crates/meerkat-rpc/src/handlers/mcp.rsPer-turn tool overlay
Per-turn tool overlay
TurnToolOverlay: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: crates/meerkat-core/src/service/mod.rs, crates/meerkat-mob/src/runtime/flow.rsDeferred 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. A Rust host can read this projection for a live session without a model request:EphemeralSessionService::tool_catalog_view and
PersistentSessionService::tool_catalog_view (and the
MobSessionService seam) return a typed ToolCatalogView. It reports the
mode the next request takes, sources still connecting, whether a staged
change waits for the next boundary, and for each catalog entry its
deferral eligibility, callability and visibility (Visible, Deferred
behind the control plane, or Hidden). Reading it changes nothing. Like
the other tool-scope snapshot queries, it is not exposed over JSON-RPC or
REST.
tool_catalog_search
tool_catalog_search
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: crates/meerkat-tools/src/control_plane.rstool_catalog_load
tool_catalog_load
ToolScope and fails closed when it has no
authoritative visibility state.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: crates/meerkat-tools/src/control_plane.rs,
crates/meerkat-core/src/tool_catalog.rsModel-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.
The switch keeps the session’s reasoning effort level and is not judged
against it. After a brain_swap to a model whose route does not accept the
session’s level, each request is refused before it reaches the provider
until the level is changed or cleared.
Source: crates/meerkat-tools/src/builtin/brain_swap.rs,
crates/meerkat-tools/src/builtin/composite.rs,
crates/meerkat-core/src/agent/state.rs, crates/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.
mob_list lists a mob only when its actor admits that the caller may manage
it. A persisted mob whose store did not restore is quarantined and has no
actor, so mob_list never lists it: the check fails closed. Hosts list
quarantined mobs through mob/list and the MCP meerkat_mob_list tool (see
Quarantined mobs and degraded members).
fork_off and council delivery
fork_off forks the calling member’s committed transcript into a durable child
member, commits the task (and any expected_output guidance) as the child’s
input, and admits the child’s one turn. The child runs turn-driven whatever
its role’s default runtime mode, like a delegate helper. What happens next
depends on whether the host can deliver a completion after the call returns.
The child, like a local council participant, is built with its source
member’s build inputs: the source’s application context and labels and the
source’s per-spawn tool overlay. The labels that name a member (mob_id,
role, profile_name, meerkat_id, agent_identity) are not inherited. The
child’s roster entry carries none of them, and its build stamps the child’s
own. Its SessionBuildOptions::fork_source names the source member and the
session the child was forked from, so a host build callback can grant the
child exactly the source’s tools and instructions. With the same tools, the
child’s first request repeats the source’s cached prompt prefix. The host’s
spawn customizer does not run on the child’s seating.
A child that is rebuilt later (revived after its session was dropped, resumed,
or restored after a restart) keeps its fork_source, labels and application
context. The host’s spawn customizer does not run on those rebuilds either, so
it cannot change them. It is revived with the tool overlay it was built with.
After a restart or explicit resume it gets the overlay its source is restored
with, as long as the source is still seated on the session the child was forked
from. Once the source has been retired or respawned, the child is rebuilt with
the overlay the host’s spawn customizer gives its own identity, and a warning
names the missing source. A fork of the child inherits the overlay the child
was built with, so grandchildren get the same tools. A grandchild follows its
source only while every ancestor its tools came through is still seated on the
session its fork was taken from, so it drops a retired ancestor’s tools too.
Its tools came through only the ancestors they passed when it was forked: if
its forker had already been rebuilt with its own identity’s tools by then, the
grandchild keeps following its forker, whatever happened above it.
Detached. A call runs detached when three things hold: the host declares
it can deliver later, it has a runtime to admit the completion, and the caller
can be made live again to receive it. A host built with a runtime adapter
declares delivery by default (the JSON-RPC, REST, and MCP servers and
Meta), and so do rkat run --keep-alive and rkat mob deploy --surface rpc. The caller can be revived when it is a member of a mob the host manages
(its mob revives it) or when the host installs a DetachedOwnerHost (the
JSON-RPC host does). A fork_off caller is always a mob member. There
fork_off returns without waiting for the child’s turn:
cache_inheritance. That is prompt-cache accounting for hosts (it stays on the
Rust ForkMemberResult and the SDK fork results); request building never reads
it, and a mob fork always reports it unavailable, which says nothing about
what the child’s turn is billed. The child’s cache cost is the usage in its
completed outcome.
When the child’s turn ends, its outcome names the child (agent_identity,
member_ref) and carries a status:
BackgroundJob system notice. Its body is the header “Background fork_off job
<job_id> finished (<status>):”, where the status is completed,
terminated for a max_run_secs autokill, or failed for every other
outcome. Its typed block, SystemNoticeBlock::BackgroundJob, carries the
job_id, the tool name, that status, the outcome JSON as detail (stored only
there), and persisted: true, which marks it as a durable completion record
rather than a progress notice that is refreshed at each model call
(SystemNoticeMessage::persisted_background_job_id finds it). The model sees
the header followed by the outcome, once.
It stays in the transcript across later model calls, turns, and reloads, and it
remains readable after the child is retired: in the transcript the model sees,
and through the forker’s session history (session/history over JSON-RPC,
GET /sessions/{id}/history over REST).
The record is delivered to the forker’s session as a runtime input with steer
handling and the idempotency key fork_off:<job_id>, so it is written exactly
once however often delivery runs:
- a forker in the middle of a turn sees it in that same turn: the notice is written into the running turn at its next model call (after that point’s tool results), every later model call of the turn sees it, and it commits with the turn, with no second turn. Only when the turn ends before another model call (the model answered without a further tool call) does the forker get exactly one follow-up turn that sees it;
- an idle forker runs exactly one wake turn that sees the outcome, and the notice is committed with that turn;
- a forker that is no longer live (the runtime retired its idle executor, or the host restarted) is revived through its mob first.
rkat CLI is one-shot unless it stays alive: rkat run without --keep-alive and the other one-shot rkat mob commands. There
fork_off waits for the child and returns the completed result as its tool
result (bounded_result, usage, turns, tool_calls, and the child’s
identity and sessions). A child that does not complete is a tool error whose
text carries the same outcome. A blocking result names why it blocked in
blocked_because: host_declared_unavailable; no_runtime_adapter for a
host that declares detached delivery but has no runtime (which also logs an
error); or no_owner_revival_host for a caller that is a plain session on a
host without a DetachedOwnerHost. A blocking call leaves no detached job
owed, so no result can be lost.
Neither form has a default deadline: the child runs for as long as its task
needs. The agent loop’s default tool deadline does not cut a blocking call. An
operator’s explicit tools.tool_timeouts.fork_off entry still bounds it, as
does a deadline the host itself imposes on tool calls. max_run_secs is an
opt-in autokill, honored in both forms, that cancels the child’s run and
retires the child once it has run that long; omit it for no limit. fork_off
rejects arguments it does not define, so a misspelled or invented field is an
argument error instead of a silently ignored intent.
Across a restart. A detached child carries a durable job record (job id,
forker session, start time, opt-in limit, fork prefix length, result bound,
and, on a runtime-backed host, the stable delivery identity its job turn is
admitted under) on its spawn event and roster entry. When a host restores its
mobs, or inserts a restored mob handle as Meta does, a one-time re-link pass
settles every child whose job began in a previous process:
- a child whose reply to the job is already in its durable transcript has
that reply delivered, however late the restart landed, and stays seated.
For a job with a delivery identity (every job on a runtime-backed host) the
outcome comes from the runtime’s terminal receipt for the job turn’s input
instead, so a child whose transcript was compacted during the job is still
delivered its real reply, with the turn’s
usage,turnsandtool_calls. That receipt also settles the other outcomes: the turn’s own failure isfailedwith its error, and the child is retired as the live custodian retires it; an end imposed from outside (the runtime stopped or destroyed, the turn cancelled), an input no run answered, or one never admitted isrestart_interrupted. So is an input that a settlement of the child’s session answered as outcome unknown (a run consumed it at a boundary a recovery committed without its receipt): that receipt carries no reply, so none is delivered. An input still owed a terminal is watched until it has one, even while the child reads idle (a requeued input waiting for the recovered run). A record without a delivery identity (written by an earlier release, or on a host without a runtime) reads the reply from the child’s transcript after the fork prefix; - a child still running is observed until its turn ends, with
max_run_secsmeasured from the original start. A turn that is terminal in the child’s live agent counts as running until its boundary commit lands: the re-link asks the child’s runtime whether a run input still awaits its boundary (MeerkatMachine::session_has_uncommitted_run_input), so a finished reply is read only once it is durable; - otherwise
restart_interruptedis delivered and the child stays seated.
COMMIT_PENDING_CEILING (5 minutes), measured from the first such reading
and restarted only when the child is seen running again. The commit is
unconfirmed while the runtime shows machine evidence that it has not landed
(a run input still staged or applied, or degraded durability after a failed
boundary commit), or while the runtime’s read is inconclusive (it timed out
behind a busy session driver, or failed). At the ceiling, unless a durable
reply has appeared, restart_interrupted is delivered. It carries
restart_reason: commit_never_landed only when the reading at the ceiling
was machine evidence; an inconclusive reading names no cause. For a job with
a delivery identity the same ceiling bounds an input still owed its terminal
while the child is not seen running; there commit_never_landed means a run
had taken the input up (staged or applied) and it never reached a terminal.
At that ceiling the receipt is read once more, waiting on the runtime for up
to two seconds (never past max_run_secs), and a receipt found then is
delivered. Only a read that is evidence (the input still owed a terminal,
never admitted, or the child without a session or retired) delivers
restart_interrupted; a read that says nothing (it timed out behind a busy
session driver, such as the turn’s own commit, even after an earlier reading
found the input pending, or it failed) keeps the watch
going, and only three such reads in a row deliver restart_interrupted,
naming no cause.
A limit that has already elapsed is decided at once, so an idle child past its
limit always gets max_run_elapsed. When the limit wins, the child’s run is
cancelled, max_run_elapsed is delivered, and the child and its descendants
are retired once that delivery settles (submitted durably, or the owner gone).
A submission that fails keeps the cancelled child and its job record, and a
later pass delivers and retires it; a child left seated after its record was
committed is retired by the next pass without a second record. A retirement
the settled outcome requires (the turn’s own failure, or max_run_elapsed)
that fails is retried for up to about ten seconds, within that child’s own
settlement, so it never holds up another child. One that still fails is
reported, as ChildRetirement::Failed in the pass’s ForkRelinkReport (and in
the ForkRelinkOutcome of fork_relink::relink_child) and as a logged
warning, and the child stays seated until the next pass retires it.
The job’s owner is its bound owner session, never read back from the child’s
roster entry: a member of the child’s mob or of another mob the host manages
is revived through its mob, and any other owner is a plain session made live
through the host’s DetachedOwnerHost. A fork_off child’s owner is its
forker, a member of the same mob; a forker that was respawned or retired
since is gone, so the job is reported as owner gone and a child past its limit
is retired with its descendants.
Delivery is the live custodian’s: the outcome is committed once with the job
(a ForkJobTerminal event in the child’s mob, with the outcome’s result
digest) and submitted to the owner as a continuation under the same record and
idempotency key (fork_off:<job_id>), so an outcome recorded before the
restart is never recorded twice, and an idle forker is woken to see it. A job
whose outcome is already committed is submitted with that outcome. A job whose
completion was already admitted is finished: the pass leaves it and its child
alone (no limit, no cancel, no second record), and a respawned child carries
no job, although its ownership still follows the identity. A job whose forker
no longer exists is reported as owner gone instead of retried. The
continuation is durable from submission: a forker that cannot be served yet,
because its mob is not running (for example restored Stopped after a clean
shutdown) or is still being revived, receives it from the host’s delivery
owner once it is, with no wait or retry of the pass’s own.
MobMcpState::relink_restored_fork_children runs the pass explicitly.
council follows the same split. Detached, it returns status: "running",
the council_id, a job_id, and a note, and the sealed outcome (result,
cleanup, replayed) is recorded and delivered the same way, as a
“Background council job <job_id> finished” notice with the idempotency key
council:<job_id>. A council that fails after the call returned is recorded
with {"error": ...} as its outcome and status failed, and so is a sealed
council whose exit reason is a failure (participant_seating_failed,
participant_fork_instruction_refused, participant_source_replaced,
wiring_incomplete, exchange_failed, coordinator_interrupted), whose
record keeps the full sealed outcome. A detached council also survives a
restart: its custody record carries the convener’s job, and the post-restore
recovery sweep delivers the council’s sealed result, or
coordinator_interrupted once the dead coordinator’s claim lease has expired
(councils are never re-executed). The sweep runs on every host whose council
store is durable and whose MobMcpState was built with into_shared() (a
state wrapped in a plain Arc::new never runs it), and it retries after the
earliest observed lease expiry;
MobMcpState::relink_detached_councils runs the re-link explicitly. Blocking, council returns the sealed outcome as its tool
result, with blocked_because. A council’s outcome is committed once on its
custody record and submitted as a continuation like a fork_off outcome. A
detached convener that is not live is revived when its continuation is
applied: through its mob when it is a mob member, or through the host’s
DetachedOwnerHost when it is a plain session. A plain-session convener on a
host without that hook (a top-level REST, MCP-server, or rkat run --keep-alive session) is not given the detached route at all: its council
runs in the call and returns with blocked_because: "no_owner_revival_host".
MobMcpState::detached_delivery_blocked_because_for(owner) reports the route
for a given caller. Its own timeout_seconds bounds it in both
forms, and the agent loop’s default tool deadline does not. See
Temporary Councils.
An embedding host declares the capability on its MobMcpState
(with_detached_completion_delivery / set_detached_completion_delivery with
DetachedCompletionDelivery::Available or Unavailable). The default follows
the presence of a runtime adapter, and detached_delivery_blocked_because
reports why the tools would block. Detached outcomes are submitted through
the host’s runtime delivery inbox, which the host binds with
MobMcpState::bind_continuations (passing the bundle’s
runtime_delivery_inbox() and continuation_bindings()); a host that does not
bind it runs the tools in the turn (no_continuation_owner). Every product
surface binds it. A host whose detached-job owners can be plain sessions
installs a DetachedOwnerHost (with_detached_owner_host /
set_detached_owner_host) so their results are applied after the runtime
retired an idle executor. Bind continuations and install the hook before
inserting restored mob handles: mob_insert_handle starts the re-link.
compose_rpc_mob_state does this for the JSON-RPC host.
Forked children belong to their forker
Ownership follows the process tree. A child created byfork_off belongs to
the member that forked it, and so does every member that child forks in turn;
ownership never flows upward. The spawner is recorded durably when the child is
seated, survives resume and respawn (including a respawn with a successor
spec), and is checked against the caller’s own session binding, never against
tool arguments. Without manage scope over the mob, the forker can still:
- read any of its descendants with
mob_check_member, which answers at once even while the member’s turn runs (progress.run_stateisrun_open, the output preview and token count are from its last completed turn, and anotesays so). Status reads of different members never hold each other up, and concurrent reads of one member share one read; a session read that outlives its 1 s deadline keeps running (and keeps its share of the mob’s read capacity) until it finishes, for at most 30 s, and later reads of that member wait on it instead of starting another. A read still running after 30 s is given up and its share released, so a stalled session store cannot hold the mob’s read capacity for longer. A read whose session view was not observed still answers, with a typedpreview_unavailablemeaning the preview and token count are missing, not empty or zero, and anotechosen by its value:observation_deadline(the read did not finish in time) andread_failedsay to check again later and that onlystatusandprogress.run_stateare current;session_absentsays the member has no readable session, so checking again will not bring the preview back;store_refusedsays the store refuses to read the member’s session until its realm is reopened, so checking again will not bring the preview back before then, and thatstatusandprogress.run_stateare current;not_observed_while_retiringsays the member is retiring and its session was not read; - retire any of its descendants with
mob_retire_member; - list its descendants, and only those, with
mob_list_members.
member_status, retire_member,
force_cancel_member, list_members) apply the same rule. With manage scope,
all of these tools reach every member, as before. A host can hide members
from other members’ operator tools (MobBuilder::with_member_tool_audience):
member_status, retire_member and force_cancel_member answer a member
its audience hides from the calling member exactly as a member the mob does
not hold, with manage scope too, and do nothing to it.
From 0.9.15 these tools keep to the audience as well: mob_check_member
and mob_retire_member answer a member the audience hides in the same way;
wire_members, unwire_members, mob_wire and
mob_unwire answer so for either member they name, and council for a
participant; spawn_member and spawn_many_members answer so for the
source of a fork launch, and refuse a resume of a session bound to such a
member as a resume of a session nobody holds; list_members and
mob_list_members leave such a member out of the list and out of every
listed member’s wired_to; and the report of mob_destroy, and the refusal
of a mob_destroy refused by the mob, name no such member. An agent is
answered such a refusal whole only when its type shows that it names
nothing the agent is not shown; any other is answered as mob destroy refused. The destroy can be retried; the host's log has the cause., on a
host with no audience too, and the host’s log holds it whole at warn. A
placed member’s calls are asked about as that member’s. The audience is
handed the labels the calling member and the target carry on their own
roster rows, so its rule can rest on a member’s durable labels.
From 0.9.15: the
other mob tools of an agent (mob_spawn_member, fork_off,
council, conclude_objective, mob_check_member, mob_retire_member,
mob_list_members, mob_wire and mob_unwire) follow the same rule for a
mob that has an audience: a refusal the mob answers is passed on whole only
when its type shows that it names nothing but the mob and the members the
call itself names, and any other is answered as the mob refused the call. The host's log has the cause., the whole refusal logged at warn. When
the refusal has a class that describes the refused operation
(wiring_error, session_error, storage_error and the like) the answer
ends with Refusal class: <class>. and carries it as class in its data.
A provider authentication failure keeps its typed data, and a retirement
still in progress keeps retryable: true. The outcome of a fork_off run
and the error of a council that could not run follow the same rule; a
council that started and then failed answers its outcome with the mob’s
own texts. A mob
with no audience answers these tools whole, with one exception on every
host: a failed read of the calling session’s own seat (fork_off,
conclude_objective) is answered as a fixed text unless its type names
nothing. Through 0.9.14 every mob answers these tools whole. A call that
seats a member still tells whether its name is taken.
In 0.9.11 through 0.9.14 only the three tools named first keep to the
audience. A member list names a member the audience hides. Through the wire
tools a member with manage scope over the mob can learn that a member hidden
from it exists and reach it. Through mob_check_member and
mob_retire_member, on a host that has not wrapped the two tools, a member
can learn that a member hidden from it exists, and one with manage scope over
the mob can read its status and retire it. The fork and resume launches and
council are not held to the audience. The report of mob_destroy can name
such a member, and a destroy the mob refuses because a member’s state could
not be restored names that member, its session and the cause to every caller.
A placed member’s operator calls reach the audience as a call no member made.
The CHANGELOG lists each of these under Security and Fixed.
A member placed on a member host holds manage scope over its mob, including
the privileged spawn arguments, unless its controlling host narrowed it with
an operator authority ceiling on its spawn request. See
Placed-member operator authority.
Retirement cascades like a process tree. Retiring a member retires every member
it transitively spawned, deepest first, then the member itself, each through
the same exact-incarnation retire; every retirement is attempted and the first
failure is reported, so a retry converges. The cascade lives in the core
retire, so every path takes it: mob_retire_member, retire_member, the
max_run_secs autokill, the retirement of a child whose turn failed,
host-side retirement (mob/retire over JSON-RPC, meerkat_mob_retire over
MCP), and MobHandle::retire itself, which Meta’s retire paths and idle
sweep use. A descendant forked while its subtree is being retired is retired
with it.
The mobs the retired member created itself and its delegates end with its
session, at the next start of the host.
A child whose own turn fails is retired automatically. A child whose turn
completes stays seated, for inspection or further work, until its forker
retires it. Meerkat adds no retention limit of its own; a host can apply one
(Meta’s idle_retire_secs, for example).
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: crates/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
Schedule tool inventory
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
WorkGraph tool inventory
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 thesession-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
Task data model
Task object returned by task tools has these fields:crates/meerkat-tools/src/builtin/types.rs — Task struct.task_create
task_create
Task object (see task data model above).Source: crates/meerkat-tools/src/builtin/tasks/task_create.rstask_get
task_get
task_list
task_list
Task objects matching the filters.Source: crates/meerkat-tools/src/builtin/tasks/task_list.rstask_update
task_update
Task object.Error: ExecutionFailed if the task ID is not found.Source: crates/meerkat-tools/src/builtin/tasks/task_update.rsShell tools
Shell tools execute commands and manage background jobs. They are alldefault_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.
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.ToolDispatcher, or Meta callback deadline. The foreground shell
and dispatcher deadlines are distinct enforced layers, even though both
defaults come from ToolTimeoutPolicy; a config’s [shell] timeout_secs sets
the shell’s. 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 configuration
ShellConfig:crates/meerkat-tools/src/builtin/shell/config.rsShell security modes
Shell security modes
SecurityEngine validates commands before execution using POSIX-compliant word splitting (shlex) and glob pattern matching (globset).crates/meerkat-tools/src/builtin/shell/security.rsshell
shell
true, durably submit a non-resumable shell job and return its stable job
ID. Requires persistent realm job and blob stores, and is advertised to the
model only when they are bound. Job truth survives restart; a lost subprocess
is classified as worker_lost, not replayed.[stderr] line only when it is non-empty.
Flags such as invalid UTF-8 appear only when set. Transcripts, tool events and
every surface carry this text as a Text content block. Only code that calls
the tool directly (BuiltinTool::call) gets the typed ShellOutput through
ToolOutput::into_json.stdout is capped at [shell] max_output_chars characters (default 40000, about
10K tokens), and stderr at half of that. The cap applies to foreground calls
and background jobs alike. Longer output keeps up to half the cap from its
start and the rest from its end. A cut moves to a line boundary when the line
it lands in fits the cap. The marker between the two sides names the omitted
lines, the line where the head ends and the line where the tail starts, and a
sed -n range that pages exactly the omitted lines:ShellOutput records it in
stdout_lossy and stderr_lossy, and the text result notes it. A character
split by the capture buffer’s edge is not invalid output and is not flagged.crates/meerkat-tools/src/builtin/shell/tool.rsmonitor_start
monitor_start
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.crates/meerkat-tools/src/builtin/shell/monitor_tool.rsshell_jobs
shell_jobs
status field is one of: "queued", "running",
"completed", "failed", "cancelled", "worker_lost", or
"needs_attention".Source: crates/meerkat-tools/src/builtin/shell/jobs_list_tool.rsshell_job_status
shell_job_status
BackgroundJob through
ToolOutput::into_json. A background job’s completion notice carries the same
exit status and output.Default enabled: No (requires shell to be enabled)ExecutionFailed if the job ID is not found.Source: crates/meerkat-tools/src/builtin/shell/job_status_tool.rsshell_job_cancel
shell_job_cancel
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)ExecutionFailed if the job ID is not found.Source: crates/meerkat-tools/src/builtin/shell/job_cancel_tool.rsShell types
Shell types
"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: crates/meerkat-tools/src/builtin/shell/types.rsMemory tool
The memory search tool lives in themeerkat-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
memory_search
limit is capped at 20 regardless of the requested value.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: crates/meerkat-memory/src/tool.rsUtility tools
Utility tools are general-purpose helpers enabled by default when builtins are on.Paths the file tools never write
apply_patch and blob_save_file run inside the host process, so no OS
process confinement applies to them. They refuse to create, change, delete or
move:
- any path in a
.rkatdirectory, the engine’s own, at the project root or in any directory under it: the project’s MCP servers (mcp.toml), hooks (config.toml) and skills, and, with the CLI’s default project-local state, the realm’s config document and stores. A host started from a subdirectory reads that directory’s.rkat, so a nested one is refused like the one at the root. The name is matched in any letter case, through.., an absolute path or a symbolic link, and when the directory does not exist yet. - any path the host declares as its own state or input that lies inside the
project root, with everything under it: the realm state root (also one
given with
--state-root), the realm’s documents (config.toml,config_state.json,realm_manifest.json, theauthorizationdirectory), the user config document, the MCP, hook and skill sources and a file credential store.rkat,rkat-rpc,rkat-restandrkat-mcpdeclare theirs. A Rust host declares its own withAgentFactory::with_protected_host_inputs(orCompositeDispatcher::protect_host_pathson a dispatcher it builds itself); without it only.rkat/is refused. - any path with a symbolic link whose target does not exist: the write would create the link’s target, wherever it points.
view_image, blob_load_file, an
update hunk’s context of an ordinary file) is not restricted by this rule,
and neither is the shell tool, whose reach its
confinement decides. To change
engine configuration, use the CLI (rkat mcp add, rkat config,
rkat auth, rkat skill add) or edit the files yourself.
A declared path that contains the project root, or is the project root, is
not applied as a whole. That is the layout of rkat-rpc and rkat-mcp
started without --context-root: they root these tools in the realm
directory itself. The realm’s documents are refused there like everywhere
else, with the hooks and skills read from that directory’s .rkat, and
other files are written as before. The realm’s stores (sessions, runtime,
jobs, tasks, blobs and the rest) lie in the same directory and are not
refused in that layout. Start the server with --context-root <dir> (SDK
option context_root / contextRoot) to give agents a project directory of
their own and keep the whole realm out of these tools’ reach. rkat-rest
without a context root roots the tools in its own instance directory, which
does not hold the realm.
Three limits of the rule: a hard link that already exists in the project to
a protected file is written through; a symbolic link deeper inside a
protected directory is not followed (the rule follows a link at
<project root>/.rkat and at each declared path, so the directory such a
link leads to is refused under its own name; a link inside it to another
place is not); and a .rkat below the project root that is itself a
symbolic link is refused by its name, not where it leads.
datetime
datetime
crates/meerkat-tools/src/builtin/utility/datetime.rsapply_patch
apply_patch
Mutating.*** 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.status: "success" plus added_files,
modified_files, and deleted_files.Source: crates/meerkat-tools/src/builtin/utility/apply_patch.rsview_image
view_image
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)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: crates/meerkat-tools/src/builtin/utility/view_image.rsblob_save_file
blob_save_file
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..rkat/ or in another of the
paths the file tools never write is
refused before anything is created.blob_id, media_type, path, and bytes_written. Raw bytes are never returned in the tool result.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rsblob_load_file
blob_load_file
blob_id, media_type, path, and bytes_read. Raw bytes are never returned in the tool result.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rsblob_inspect
blob_inspect
blob_id, media_type, and decoded size_bytes.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rsgenerate_image
generate_image
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.intent, prompt, instruction, source_images, reference_images, size, quality, format, count/n, target, provider, model, and provider_params.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.6-sunburst 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, opaque or transparent (transparent needs format png or webp; with jpeg it is denied with projection_unsupported), output_compression applies when format is jpeg/webp, moderation is auto or low, action is usually omitted in favor of top-level intent, a low, medium or high reasoning_effort also sets a GPT Image 2.6 model’s planning complexity, 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: crates/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
web_search
openai, gemini, or anthropic. When present it must
match the fallback provider selected for the session.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.status is completed when a provider-native search event was observed,
unavailable when the stream showed none (the search is unverified; any
answer is still included and error says so), and failed when the native
search call stopped on a refusal, a content filter, a filled context window
or a cancellation: error then names the stop and the result has no answer,
evidence or native events. A call cut at its output cap (max_tokens) or
paused by the provider’s server-tool loop (pause_turn) keeps its status and
answer, and error says the answer may be incomplete. This holds since
0.9.4; 0.9.3 and earlier reported a refused search’s text as a completed
or unavailable answer.This tool is classified read-only. Visibility is controlled by
override_web_search, independently from general builtins.Source: crates/meerkat-tools/src/builtin/web_search.rsComms tools
Comms tools enable inter-agent communication. They require thecomms 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_message
image_ref entries (source: "current_turn" with index, or source: "blob" with blob_id and media_type)."queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.crates/meerkat-comms/src/mcp/tools.rssend_request
send_request
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)"checksum_token" or "supervisor.bridge". Unknown intents fail at the serde boundary."queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.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.require_peer_auth = false, the key the envelope declares). The
request stays open for its addressee.Source: crates/meerkat-comms/src/mcp/tools.rssend_response
send_response
"queue" or "steer". Forbidden on "accepted" progress responses.require_peer_auth = false, the key the envelope declares). A peer_id that
is not the requester fails with invalid_arguments and nothing is sent; the
request stays open. display_name never changes the addressee. A request ID
this session did not receive or has already answered fails with
execution_failed, as before.Source: crates/meerkat-comms/src/mcp/tools.rspeers
peers
peer_id for sends.Default enabled: Yes (when comms is active)Parameters: None (empty object).crates/meerkat-comms/src/mcp/tools.rs — PeersInputSkill tools
The five skill tools are registered only when aSkillRuntime 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 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: crates/meerkat-tools/src/builtin/skills/browse.rs,
crates/meerkat-tools/src/builtin/skills/load.rsSkill resources and functions
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: crates/meerkat-tools/src/builtin/skills/resources.rs,
crates/meerkat-tools/src/builtin/skills/functions.rsCargo feature gates
Tool availability depends on compile-time features in themeerkat-tools crate:
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: crates/meerkat-tools/Cargo.toml