Spawning & coordinating agents

The Operator MCP is Revka’s orchestration brain. It exposes a set of MCP tools that let your agent spawn sub-agent subprocesses, manage their lifecycle, reuse standardized agent templates, track goals and plans, journal and archive sessions, record outcomes, compact long conversations, and enforce permission and autonomy policy before anything runs.

This page covers those orchestration primitives as MCP tools. Use it when you want one agent to coordinate others — a coder + reviewer loop, a research fan-out, or a long-running task that needs to remember what it learned. For higher-level structures built on top of these primitives, see Agents, teams & swarms and the dashboard’s Agents, teams & canvas page.

Note

These tools live in the operator sidecar and are only present when it is installed and running. See Install the Python MCP sidecars and Operator MCP for setup. Each agent chat session gets a fresh operator process with its own session_id.

Spawn an agent with create_agent

create_agent spawns a new coding-agent subprocess. It can run any of five supported CLI backends, optionally inherit from an agent template, restrict the agent to a tool allowlist, and run in a sanitized environment for build/test work.

{
  "title": "rust-coder",
  "cwd": "/home/user/myproject",
  "agent_type": "codex",
  "initial_prompt": "Implement the auth module",
  "template": "rust-coder",
  "model": "claude-opus-4-5",
  "allowed_tools": ["Read", "Edit", "Bash"],
  "max_turns": 100,
  "parent_id": "<uuid>",
  "clean_build": true
}

Parameter	Type	Required	Meaning
title	string	yes	Short label for the agent (max 60 chars).
cwd	string	yes	Absolute working directory. Always pass it explicitly, even with a template.
agent_type	enum	no	CLI backend: claude, codex, agy, agent, or opencode. Overrides the template’s type.
initial_prompt	string	no	Prompt sent on creation.
template	string	no	Pool template name; inherits agent_type, default_cwd, and system_hint.
model	string	no	Model hint for CLIs that support model selection.
allowed_tools	string[]	no	Tool allowlist. Omit to allow all tools.
max_turns	integer	no	Max conversation turns before auto-stop. Default 200.
parent_id	string	no	Parent agent UUID for hierarchical spawning and cache-safe prompt reuse.
clean_build	boolean	no	Use a sanitized environment (strict var allowlist, cleared build caches). Default false. Recommended for build/test agents.
node_env	string	no	NODE_ENV for the agent process. Default development.

Agents are identified by a UUID returned in the response. Use that UUID with every lifecycle tool below.

Tip

For Google ADK / Agent Engine lifecycle work, spawn a claude or codex agent and let it call google_agents_cli rather than introducing a new agent type. For reaching external agents over the network, see A2A protocol & cloud agents.

Agent lifecycle tools

Once an agent is running, these tools drive it through its lifecycle — waiting, follow-up prompts, inspection, cancellation, and cleanup.

Tool	What it does
wait_for_agent(agent_id, timeout?)	Block until the agent finishes. Default timeout 120s.
send_agent_prompt(agent_id, prompt)	Send a follow-up prompt to an idle or completed agent.
get_agent_activity(agent_id)	Structured summary: status, tool-call count, error count, files touched, last failing command, usage stats.
get_agent_run_log(agent_id, view?, limit?)	Detailed run log. view: summary (default), tool_calls, errors, files, full. limit default 50. Works for running and completed agents.
list_agents()	All managed agents with identity metadata (id, sidecar id, backend, title, status, cwd).
list_run_logs()	All run logs available on disk.
get_agent_health(agent_id?)	Heartbeat / liveness info; detects stuck agents. Omit agent_id for all agents.
diff_agent_artifacts(agent_a, agent_b)	Compare two agents’ files touched, output similarity, tool-call patterns, and error divergence.
get_workflow_context(view?, agent_id?, status_filter?)	Accumulated findings from completed agents in this session. view: summary, findings, finding.
cancel_agent(agent_id)	Cancel a running agent. Subprocesses use graceful signal escalation SIGINT → SIGTERM → SIGKILL; sidecar agents use interrupt + close.
cancel_all_agents()	Cancel every running agent; returns per-agent results.
prune_completed_agents(older_than_seconds?, include_idle?, include_cancelled?, include_failed?, dry_run?)	Remove inactive runtime records while preserving run logs and workflow history. older_than_seconds default 60; the include flags default true.

Caution

The wait_for_agent default timeout of 120s is often too short for agents doing 30+ tool calls. Pass timeout: 180 (or higher) for longer tasks. Use prune_completed_agents with dry_run: true first to preview what would be removed.

Agent template pool

The template pool is a persistent registry of reusable agent definitions stored in Kumiho under <harness>/AgentPool/. Each template captures an agent’s type, role, capabilities, identity, soul, tone, preferred model, and default working directory, so create_agent and orchestration patterns can instantiate standardized agents by name.

Tool	What it does
search_agent_pool(query)	Keyword search over name, role, capabilities, and description.
save_agent_template(name, agent_type, role, capabilities, description, identity?, soul?, tone?, default_cwd?, system_hint?, model?)	Create or update a template.
list_agent_templates()	List all templates, sorted by usage count.
get_agent_trust(template_name?)	Trust score for a template: success rate, total runs, and recent outcomes. Omit template_name for all scored templates.

{
  "name": "rust-coder",
  "agent_type": "codex",
  "role": "coder",
  "capabilities": ["rust", "testing"],
  "description": "Senior Rust engineer for systems work.",
  "identity": "Senior Rust engineer with 10+ years of systems experience.",
  "soul": "Correctness first, performance second.",
  "tone": "Technical, direct, precise.",
  "model": "claude-opus-4-5"
}

• role is one of coder, reviewer, researcher, tester, architect, planner.
• agent_type is one of claude, codex, agy, agent, opencode.
• Usage count is tracked automatically each time a template is used, which is why list_agent_templates() sorts by it.

Trust scores accumulate as you record outcomes (see Outcome recording). They feed pattern selection — for example, the refinement loop auto-switches critics when a template’s trust drops below 0.7.

Goals hierarchy

Goals are tracked hierarchically in Kumiho under Revka/Goals/. Goals form a tree (strategic → tactical → task-level) via parent_kref, each with a status and priority.

Tool	What it does
create_goal(name, description, status?, priority?, parent_kref?)	Create a goal. status default active; priority default p1.
get_goals(status?, priority?)	List goals, optionally filtered by status or priority.
update_goal(kref, status?, priority?, description?)	Update a goal’s fields.

• status: active, completed, blocked, deferred.
• priority: p0, p1, p2, p3. Treat p0/p1 as long-lived strategic objectives and p2/p3 as task-level items.
• Pass parent_kref to nest sub-goals under a parent.

Execution planning and recall

Plans are persistent records of how a complex task was decomposed, stored in Kumiho under Revka/Plans/. Recalling similar past plans before you decompose a new task is the operator’s main learning mechanism.

Tool	What it does
save_plan(name, task_description, steps, agents_used?, outcome, lessons?)	Save a plan with its steps, agents, and result. outcome: success, partial, failed.
recall_plans(query)	Semantic search over past plans by task description.

Tip

Call recall_plans before decomposing a complex multi-agent task to reuse what worked. Always fill in lessons when saving — that field records what worked, what didn’t, and what to do differently next time.

Session journal and archiving

The operator keeps a local NDJSON journal of agent lifecycle events at ~/.revka/operator_mcp/session.ndjson, one record stream per session. Significant sessions can be archived to Kumiho for long-term recall under Revka/Sessions/.

Tool	What it does
get_session_history(session_id?, agent_id?, limit?, list_sessions?)	Recall past sessions and lifecycle events from the journal. limit default 30. Set list_sessions: true for a per-session summary.
archive_session(title, summary, outcome, session_id?)	Archive a completed session to Kumiho. outcome: success, partial, failed. session_id defaults to the current session.
get_journal_health()	Journal size, write latency, and rotation status; detects disk issues before they cause data loss.

Because each agent chat session starts a fresh operator process with a new session_id, get_session_history is how you resume context after a restart. Call archive_session after any significant multi-agent task to build institutional memory.

Outcome recording

Outcomes are append-only memories that record what an agent (or a skill) discovered or decided. They are stored per session under <harness>/Sessions/<session_id>/Outcomes/, and downstream agents in the same workflow or handoff chain inherit them. Recording an outcome with both a template name and a status also updates that template’s rolling trust score.

Tool	What it does
record_agent_outcome(session_id, title, kind?, content?, agent_id?, agent_kref?, template_name?, status?, tags?, related_files?, related_krefs?)	Record an agent outcome. kind: discovery (default), decision, lesson, insight, warning, fact, outcome. Pass template_name + status to also update trust.
recall_session_outcomes(session_id, sibling_sessions?, query?, kinds?, limit?)	Inherit findings recorded by sibling agents in the same (or related) sessions. limit default 10.
record_skill_outcome(skill_name?/skill_kref?, success, summary?, error?, agent_id?, session_id?, duration_ms?)	Record whether a single skill use succeeded.
get_skill_effectiveness(skill_name?/skill_kref?, limit?)	Rolling success rate for a skill: {total, successes, failures, rate, recent[]}. limit default 50.

Tip

Call record_agent_outcome with template_name + status after wait_for_agent completes — this is how the agent trust database accumulates. Call recall_session_outcomes at the start of each new agent in a workflow so it inherits prior siblings’ learnings. Pass related_krefs to create INFORMS provenance edges from inputs to the outcome.

Context compaction

When a conversation grows too long, the operator can compact it into a structured summary. This is a deliberate two-step process: first ask for a 9-section prompt template, apply it to your conversation to produce the summary, then store the result. Compacted summaries are saved in Kumiho under CognitiveMemory/compactions/<session_id>.

1. Get the template. Call compact_conversation(session_id?, reason?). It returns a 9-section prompt template. reason is informational (e.g. auto-threshold, manual, session-end) and defaults to manual.

2. Apply it. Run the returned template against your conversation to generate the compacted output, including its <analysis> and <summary> tags.

3. Store the result. Call store_compaction(raw_output, session_id?, source_krefs?) with the full applied output. Pass source_krefs to link the compaction back to the memories it derived from.

Permission management

Agents running in the session manager can pause to request approval before performing potentially dangerous operations. The operator surfaces those pending requests so they can be approved or denied.

Tool	What it does
list_pending_permissions()	List all pending permission requests across managed agents.
respond_to_permission(request_id, action)	Resolve a request. action: approve or deny.

Permission requests are tracked per agent in the session manager. This is the runtime approval surface that pairs with the broader Autonomy levels & approvals model.

Policy and autonomy control

Before spawning an agent in an unfamiliar directory or running a shell command, you can run a pre-flight policy check. Policy is loaded from ~/.revka/config.toml and validates a working directory, command, or tool against the configured autonomy rules.

Tool	What it does
check_policy(cwd?, command?, tool?)	Pre-flight check. Returns structured pass/fail with the policy rule that decided it. cwd is checked against allowed roots / forbidden paths, command against allowed commands / high-risk patterns, tool against auto-approve / always-ask lists.
get_policy_summary()	Current autonomy summary: policy level, allowed roots, command counts, and risk settings.

The autonomy level is one of supervised (default), autonomous, or locked. Policy keys read from config.toml include:

Key	Type	Default	Meaning
level	string	supervised	Autonomy level: supervised, autonomous, or locked.
workspace_dir	string	~/.revka/workspace	Default workspace root.
workspace_only	bool	true	Restrict agents to the workspace unless a path is in allowed_roots.
allowed_roots	string[]	[]	Additional roots agents may work under.
forbidden_paths	string[]	[]	Paths that are always blocked.
allowed_commands	string[]	[]	Commands permitted for shell execution.
auto_approve	string[]	[]	Tools auto-approved without a prompt.
always_ask	string[]	[]	Tools that always require approval.
require_approval_for_medium_risk	bool	true	Gate medium-risk commands behind approval.
block_high_risk_commands	bool	true	Block high-risk command patterns outright.
max_actions_per_hour	int	20	Rate limit on agent actions.
max_cost_per_day_cents	int	500	Daily LLM spend cap, in cents.

Note

A check_policy failure returns the policy_rule (the config key that triggered it) and a suggestion for what to do about it. Paths are resolved through symlinks before checking, so symlinked paths cannot bypass forbidden_paths. For the full security picture, see Policy, commands & sandboxing and the Security model.

Related pages

Operator MCP The sidecar that hosts every tool on this page.

Agents, teams & swarms Teams, waves, and orchestration patterns built on these primitives.

Autonomy levels & approvals The approval model behind permission requests.

A2A protocol & cloud agents Reach external agents over the network.

Kumiho graph memory Where goals, plans, sessions, and outcomes are stored.

Policy, commands & sandboxing The full policy and sandboxing reference.