AgentNave is a local STDIO MCP server that lets an agent manager launch and supervise provider CLI subagents as disposable invocations.
Start a subagent from supported providers: antigravity, claude, codebuddy, or grok.
Provide a prompt, an absolute existing working directory, optional session ID, timeout, and provider-specific options.
Immediately receive an in-memory invocation_id for each started subagent.
Wait on an invocation to get a running snapshot or its finalized result with status, output, session ID, usage, duration, and error details.
Cancel a running invocation and receive its terminal result.
Reuse a provider session ID from a previous finished invocation to continue work.
Inherit provider-native configuration unless explicit allowlisted provider_options are supplied.
Perform best-effort cleanup of provider process groups when the MCP server stops.
Leave planning, parallelism, review, synthesis, retries, permissions, and worktree management to the calling agent manager.
A thin local bridge from Agent Managers to CLI subagents.
AgentNave lets an Agent Manager launch Antigravity CLI, Claude Code, CodeBuddy Code, Codex CLI, or Grok CLI through three lifecycle tools and one read-only provider-description tool. Each provider keeps its native authentication, configuration, permissions, and session model; AgentNave supplies the adapter and process supervision around it.
The boundary is intentional. AgentNave does not plan tasks, assign roles, build DAGs, choose parallelism, review results, synthesize answers, retry work, or manage worktrees. Those decisions belong to the calling Agent Manager, where the full task context already exists.
AgentNave has no human-facing CLI. The agentnave-mcp command is only the STDIO entry point used by
a compatible MCP host.
AgentNave | Calling Agent Manager |
Provider command adapters | Planning and task decomposition |
In-memory invocation lifecycle | Provider and model selection |
POSIX process groups / Windows Job Objects | Parallelism, review, and synthesis |
Normalized terminal results | Retries, permissions, and worktrees |
Related MCP server: pokeclaw
Windows, macOS, or Linux
uv and Git (for installation from a release tag)
At least one authenticated provider CLI
uv installs AgentNave in an isolated Python 3.12 environment. A separately managed system
Python is not required.
AgentNave uses dedicated POSIX process-group supervisors on macOS/Linux and kill-on-close Windows Job Objects on Windows. Windows providers are created suspended, assigned to the Job Object, and only then resumed so descendants cannot start outside the owned process tree.
Install the MCP runtime and companion agentnave-manager Skill as a pair. The runtime exposes the tools; the Skill teaches the calling Agent how to use other CLIs. Planning, scheduling, review, retry decisions, and synthesis remain with the calling Agent.
Follow the installation guide to:
Check the existing runtime's source, version and launcher; reuse it when suitable, or install
the missing runtime with uv tool.
Inspect the target host's effective MCP registration; reuse matching settings and add only a missing entry, with the host's provider exclusions.
Reuse the matching Skill or install its complete directory, including references/, from
the same release. Existing shared sources need only a discovery entry for the new host.
Verify both MCP tools and Skill discovery; restart connections or sessions after changes.
Hosts under the same OS user and uv tool directories share installation files, but each MCP
connection runs its own STDIO service process. Adding a host does not require reinstalling the
runtime or authorize upgrading it for other hosts. The guide covers differences and shared updates.
The guide covers host registration, provider paths, Skill installation, paired upgrades, rollback,
and removal. Provider CLIs must be installed and authenticated separately. uv manages only the
runtime; it does not install the Skill or modify provider permissions and configuration.
The paired release is v0.10.0. Install the runtime and complete Skill directory from that
tag. uv tool installs only the runtime; Skill discovery is a separate step. Hosts without
Skill support can still use MCP alone. The older v0.5.0 tag contains only the runtime.
v0.10.0 is the first paired release with native Windows support.
AgentNave creates no durable user data. Provider authentication and configuration remain owned by their respective CLIs.
This section describes v0.10.0, which adds native Windows process-tree supervision while retaining
the fixed five-minute wait contract introduced in v0.9.0.
Start, wait and cancel use flat lifecycle responses; callers upgrading from v0.6.0 must also
update their response handling and paired Skill.
Restart the MCP connection after updating the runtime to refresh its schemas.
AgentNave exposes four tools. The initial tool metadata contains a compact provider directory; provider-specific options are returned only when requested. Model defaults live in the Skill's per-CLI reference files, loaded only for the selected CLI.
describe_providerCall with the selected provider before its first use in the current context. Returns that
provider's permitted status and supported options.
Reuse the result for later calls with the same provider. This tool neither launches a CLI nor
checks installation or authentication; it does not consume provider quota or change the tool list.
For example: describe_provider({"provider": "grok"}) → start_agent(...) → wait_agent(...).
start_agentStarts one provider invocation and immediately returns an in-memory invocation_id. It requires
provider, prompt, and an absolute existing cwd; session_id and explicit
provider_options are optional.
Supported providers are antigravity, claude, codebuddy, codex, and grok. The Skill provides model and effort defaults for the Manager to pass explicitly through
allowlisted options. User choices override that guidance; omitted options still inherit native
settings. Exclusions are configured per host process, independently of the model it uses. For Codex calls outside a
Git repository, the Manager must pass
{"skip_git_repo_check": true} in provider_options.
To override the defaults for one task, tell your calling Agent the provider, model ID, and
reasoning effort. For example: “Use Codex CLI with model gpt-6-astra and effort medium.”
The Agent passes {"model": "gpt-6-astra", "effort": "medium"} in provider_options.
Only specified fields override the Skill guidance. To keep your choices across tasks, put the
same preference in your calling Agent's personal instructions. To use the CLI's native settings,
explicitly ask the Agent to omit the corresponding options.
When a new model becomes available, use its exact ID from that provider's model list; updating
AgentNave is not required to pass a new model ID. If you maintain a source installation and want
to change the bundled defaults, edit the selected CLI file in
skills/agentnave-manager/references/, then reload the Skill in a fresh context. An unavailable
model should be reported rather than silently replaced.
wait_agentEach request has a fixed five-minute (300-second) wait window; wait_agent accepts only
invocation_id. Completion or a recognized execution blocker returns early. Expiry leaves the
invocation running; call again with the same ID to continue. If a host yields a background
call handle, resume that call using the host's wait mechanism before issuing another request.
Start, wait and cancel use one flat response: invocation_id, status, reason, elapsed_ms,
plus applicable activity, error, output, output_age_ms and session_id fields. Reasons are
started, wait_elapsed, execution_blocked and finished. Running replies include the latest
public reply tail (at most 1,000 Unicode characters), retained across tool events, and its age.
No new public reply means the same tail can recur; unavailable fields are omitted. There is no
cursor, pagination or separate output-reading tool. Final replies are not subject to the tail limit.
Provider usage/cost, native event names, tool call IDs, tool payloads and thinking are not returned.
Public replies may still contain task data; this is not a redaction service.
execution_blocked leaves status=running: the Manager decides whether to keep waiting or cancel.
Each recognized blocker category wakes once per invocation, avoiding repeated immediate returns
from the same retry loop. Ordinary tool failures, transient retries and silence do not imply a
blocker; unrecognized errors may only become visible in output or the final result. There is no
unsolicited completion/error push without a pending wait request.
Wait expiry never terminates the invocation. AgentNave has no total runtime deadline and
start_agent has no runtime-limit parameter. Keep waiting for the result or use cancel_agent
to stop work explicitly. Provider-native limits still apply.
cancel_agentStops an invocation and returns its terminal result. Use it only when the Manager intends to end
active provider work; wait_agent observes without cancelling.
All four tools publish input and output JSON Schemas. Agent-correctable request errors are MCP Tool errors with retry guidance; provider launch and execution outcomes remain structured Invocation Results.
Invocation handles live only in the current MCP server process. When the server stops, AgentNave
makes a best-effort attempt to terminate processes that remain in the provider process tree. A
restart cannot recover old handles, but a retained provider session_id can be supplied to a new
start_agent call.
Running responses help inspect health and direction using a bounded public reply and native activity. They do not show every active operation or guarantee progress. Raw streams remain bounded in process memory; no output log/database is added. A 1,000-character reply tail is kept per invocation for waiting responses. Final results remain available for this server process.
Use the project directory as cwd so the CLI can load its native project rules. Temporary
handoff files do not change that directory. Antigravity can choose a different terminal Cwd:
state the absolute project directory in the handoff, require that terminal directory explicitly,
and verify it with pwd before project operations. This is a behavioral instruction, not enforced
directory isolation. provider_options.project selects a native project ID or name; it is not a
working-directory override. The companion Skill guides task handoffs and keeps
intermediate files in OS temporary storage without imposing Markdown or a result-file format.
AgentNave itself uses stdin/in-memory output except for Grok's temporary prompt file, which is
removed after use. Provider-owned history and caches remain under provider control.
AgentNave is not a sandbox. On POSIX, a same-user provider with command permission can deliberately daemonize, kill its supervisor, or otherwise escape ordinary process-group cleanup. Windows Job Objects provide tree ownership but do not isolate the provider from the user account or the rest of the machine. Provider-native permissions remain the security boundary; use OS-level isolation when adversarial containment is required.
These checks are for a development checkout, not the uv tool installation above. See
CONTRIBUTING.md for the complete contributor workflow.
uv sync --locked --all-groups
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytestContributions are welcome through GitHub Issues and pull requests. See CONTRIBUTING.md for the development workflow and validation requirements.
Do not report security vulnerabilities in a public Issue. Follow SECURITY.md to use the repository's private vulnerability reporting channel.
AgentNave is licensed under the MIT License.
Stop a task by invocation_id; use wait_agent to observe without stopping.
Returns the cancelled or already-finished result. Does not undo prior CLI side effects.
| Name | Required | Description | Default |
|---|---|---|---|
| invocation_id | Yes | Invocation ID returned by start_agent. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| output | No | |
| reason | Yes | |
| status | Yes | |
| activity | No | |
| elapsed_ms | Yes | |
| session_id | No | |
| invocation_id | Yes | |
| output_age_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool destructive and idempotent. The description adds meaningful context beyond that: it returns the cancelled result even if already finished and clarifies that prior CLI side effects are not rolled back. This goes beyond the annotation flags and exposes the real behavioral contract.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: the first states the action and distinguishing alternative, the second covers return behavior and side-effect scope. It is short, front-loaded, and free of filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with a full input schema, an output schema, and annotations, the description covers the action, the key alternative, return behavior, and a critical side-effect limitation. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the only parameter, invocation_id, is already documented as the ID returned by start_agent. The description mentions 'by invocation_id' but adds no extra semantic detail beyond the schema. Baseline 3 is appropriate because the schema carries the full burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Stop a task by invocation_id.' It directly names the sibling it is not ('use wait_agent to observe without stopping'), so an agent can clearly distinguish cancellation from observation without inspecting other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool versus the main alternative: use wait_agent 'to observe without stopping.' It also adds a decision-relevant constraint, 'Does not undo prior CLI side effects,' which helps the agent choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one provider's permitted status and supported options.
Does not launch a CLI or check installation/login. Excluded providers cannot be started.
| Name | Required | Description | Default |
|---|---|---|---|
| provider | Yes | Provider whose permitted status and options to return. |
| Name | Required | Description |
|---|---|---|
| provider | Yes | |
| permitted | Yes | |
| supported_options | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful non-effect context: it does not launch a CLI or check installation/login, and it communicates that excluded providers cannot be started. This goes beyond the structured hints and clarifies what the tool does not trigger.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary purpose front-loaded in the first sentence. The second sentence adds boundary behaviors without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one required parameter, an output schema, and annotations covering its read-only/idempotent nature. The description supplements the structured fields with non-action clarification and the exclusion consequence, so nothing essential is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage; the single required parameter 'provider' is already described as 'Provider whose permitted status and options to return.' The tool description adds no additional parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a clear verb and resource: 'Read one provider's permitted status and supported options.' The sibling tools are all lifecycle actions (start_agent, wait_agent, cancel_agent), so the read-only nature of this tool is immediately distinguishable. The title 'Read one CLI's permitted status and options' reinforces the same purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states explicitly what the tool does not do ('Does not launch a CLI or check installation/login'), which guides an agent away from using it for launching or environment verification. The final sentence 'Excluded providers cannot be started' implies that this tool returns exclusion status relevant to starting a provider, giving context for when to call it before start_agent. However, it doesn't name the sibling or state a direct condition like 'use this before start_agent', so it stops short of the most explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start one CLI invocation and return its invocation_id; use wait_agent for the result.
AgentNave imposes no runtime deadline; use cancel_agent to stop work explicitly. Provider-native limits still apply. Active invocations do not accept messages. To continue a finished conversation, pass its returned native session_id with a new prompt to a new start_agent call.
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | Yes | Absolute existing directory where the subagent runs. | |
| prompt | Yes | Complete task, context, constraints, and expected output; the CLI does not inherit this conversation. | |
| provider | Yes | CLI requested by the user, not a model ID. Providers permitted by this host configuration: antigravity, claude, codebuddy, codex, grok. Excluded providers: none. Excluded providers are rejected before launch. | |
| session_id | No | To continue a conversation, use the session_id returned by a finished invocation of the same provider; omit for a new conversation. Never use an invocation_id here. | |
| provider_options | No | Explicit options for the selected CLI. Call describe_provider(provider) for supported keys. Omitted options inherit native CLI settings. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| output | No | |
| reason | Yes | |
| status | Yes | |
| activity | No | |
| elapsed_ms | Yes | |
| session_id | No | |
| invocation_id | Yes | |
| output_age_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond annotations: AgentNave imposes no runtime deadline, provider-native limits still apply, and active invocations reject messages. It also clarifies the continuation pattern with session_id. This goes well beyond the readOnly/destructive hints, and there is no contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tightly written sentences with the primary action and result front-loaded. Each subsequent sentence earns its place by addressing deadline, alternatives, or continuation—no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich output schema and fully described parameters, the description covers all necessary operational aspects: lifecycle, result retrieval, cancellation, deadlines, provider limits, and conversation continuation. Nothing an agent needs to select and call the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage with detailed descriptions (e.g., provider exclusions, session_id 'never use an invocation_id', prompt requirements). The tool description itself adds little parameter-specific detail beyond reinforcing the session_id continuation workflow, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Start one CLI invocation and return its invocation_id', pairing a specific verb with a concrete resource and output. It immediately distinguishes itself from wait_agent and cancel_agent, so an agent understands exactly what this tool accomplishes versus its siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names wait_agent for retrieving results and cancel_agent for stopping work, and explains when to use session_id to continue a conversation with a new call. It also notes that active invocations do not accept messages, covering the main alternative flows without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for a fixed window of five minutes; completion or an explicit CLI execution blocker returns early.
Running responses include the latest public reply tail (at most 1000 characters) and its age. execution_blocked leaves the CLI running: continue waiting or cancel with the same ID. Each blocker category wakes once per invocation. Ordinary tool failures, transient retries, and silence are not proof the task cannot proceed. Finished responses contain the final reply. Wait expiry leaves the invocation running. Call again with the same ID to continue. This is request/response waiting, not a background notification subscription.
| Name | Required | Description | Default |
|---|---|---|---|
| invocation_id | Yes | Invocation ID returned by start_agent. |
| Name | Required | Description |
|---|---|---|
| error | No | |
| output | No | |
| reason | Yes | |
| status | Yes | |
| activity | No | |
| elapsed_ms | Yes | |
| session_id | No | |
| invocation_id | Yes | |
| output_age_ms | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the annotations, disclosing the five-minute window, early-return conditions, response contents (reply tail and age), wait-expiry behavior, continuation semantics, and the fact that ordinary failures/retries/silence are not proof of failure. It also clarifies the interaction model, which is valuable non-obvious behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries necessary behavioral guidance. The most important facts are front-loaded: wait window, early return, and continuation behavior. There is no filler or redundant repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a wait/polling tool with one parameter, an output schema, and safety annotations, the description fully covers invocation lifecycle, return semantics, continuations, cancellation, and failure interpretation. The presence of an output schema means return values need not be enumerated in prose, and the description supplies all missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the single parameter clearly described as the ID returned by start_agent. The description adds further semantics by emphasizing that the same ID is reused for continued waiting and cancellation, reinforcing that invocation_id is a stable handle across operations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Wait'), a fixed resource ('a subagent invocation'), and a concrete duration ('five minutes'), making the tool's role unmistakable. It also distinguishes itself from sibling tools by clarifying this is 'request/response waiting' rather than a background notification subscription.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: call again with the same ID after expiry, continue waiting or cancel when execution_blocked, and expect early returns on completion or blockers. It does not explicitly name start_agent or cancel_agent as alternatives, though it references cancellation with the same ID, so the guidance is clear but not fully explicit about sibling routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.9.0cancel_agent1 field changedOutput schema / properties / status / enumPrevious value: -[
- "running",
- "succeeded",
- "failed",
- "blocked",
- "cancelled",
- "timed_out"
-]New value: +[
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled"
+]start_agent2 fields changedInput schema / properties / timeout_secondsRemoved value: -{
- "anyOf": [
- {
- "exclusiveMinimum": 0,
- "maximum": 86400,
- "type": "number"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional total runtime limit in seconds; expiry stops the invocation. Omit or null for no AgentNave deadline; native CLI limits still apply.",
- "title": "Timeout Seconds"
-}Output schema / properties / status / enumPrevious value: -[
- "running",
- "succeeded",
- "failed",
- "blocked",
- "cancelled",
- "timed_out"
-]New value: +[
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled"
+]wait_agent2 fields changedInput schema / properties / wait_timeout_secondsRemoved value: -{
- "default": 600,
- "description": "Seconds to wait for this response; expiry leaves the invocation running.",
- "exclusiveMinimum": 0,
- "maximum": 600,
- "title": "Wait Timeout Seconds",
- "type": "number"
-}Output schema / properties / status / enumPrevious value: -[
- "running",
- "succeeded",
- "failed",
- "blocked",
- "cancelled",
- "timed_out"
-]New value: +[
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled"
+]v0.7.0cancel_agent19 fields changedOutput schema / $defs / ActivityPayloadAdded value: +{
+ "properties": {
+ "age_ms": {
+ "title": "Age Ms",
+ "type": "integer"
+ },
+ "kind": {
+ "title": "Kind",
+ "type": "string"
+ },
+ "state": {
+ "title": "State",
+ "type": "string"
+ },
+ "tool_name": {
+ "title": "Tool Name",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "title": "ActivityPayload",
+ "type": "object"
+}Output schema / $defs / InvocationErrorPayload / properties / detailsRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Details"
-}Output schema / $defs / InvocationErrorPayload / requiredPrevious value: -[
- "code",
- "message",
- "details"
-]New value: +[
+ "code",
+ "message"
+]Output schema / $defs / InvocationResultPayloadRemoved value: -{
- "properties": {
- "duration_ms": {
- "title": "Duration Ms",
- "type": "integer"
- },
- "error": {
- "anyOf": [
- {
- "$ref": "#/$defs/InvocationErrorPayload"
- },
- {
- "type": "null"
- }
- ]
- },
- "output": {
- "title": "Output",
- "type": "string"
- },
- "provider": {
- "$ref": "#/$defs/ProviderName"
- },
- "provider_usage": {
- "$ref": "#/$defs/ProviderUsagePayload"
- },
- "session_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Session Id"
- },
- "status": {
- "$ref": "#/$defs/InvocationStatusName"
- }
- },
- "required": [
- "status",
- "provider",
- "output",
- "session_id",
- "provider_usage",
- "duration_ms",
- "error"
- ],
- "title": "InvocationResultPayload",
- "type": "object"
-}Output schema / $defs / InvocationStatusNameRemoved value: -{
- "enum": [
- "succeeded",
- "failed",
- "blocked",
- "cancelled",
- "timed_out"
- ],
- "type": "string"
-}Output schema / $defs / ProviderNameRemoved value: -{
- "enum": [
- "antigravity",
- "claude",
- "codebuddy",
- "codex",
- "grok"
- ],
- "type": "string"
-}Output schema / $defs / ProviderUsagePayloadRemoved value: -{
- "properties": {
- "num_turns": {
- "title": "Num Turns",
- "type": "integer"
- },
- "total_cost_usd": {
- "title": "Total Cost Usd",
- "type": "number"
- }
- },
- "title": "ProviderUsagePayload",
- "type": "object"
-}Output schema / properties / activityAdded value: +{
+ "$ref": "#/$defs/ActivityPayload"
+}Output schema / properties / elapsed_msAdded value: +{
+ "title": "Elapsed Ms",
+ "type": "integer"
+}Output schema / properties / errorAdded value: +{
+ "$ref": "#/$defs/InvocationErrorPayload"
+}Output schema / properties / outputAdded value: +{
+ "title": "Output",
+ "type": "string"
+}Output schema / properties / output_age_msAdded value: +{
+ "title": "Output Age Ms",
+ "type": "integer"
+}Output schema / properties / reasonAdded value: +{
+ "enum": [
+ "started",
+ "wait_elapsed",
+ "execution_blocked",
+ "finished"
+ ],
+ "title": "Reason",
+ "type": "string"
+}Output schema / properties / resultRemoved value: -{
- "$ref": "#/$defs/InvocationResultPayload"
-}Output schema / properties / session_idAdded value: +{
+ "title": "Session Id",
+ "type": "string"
+}Output schema / properties / stateRemoved value: -{
- "const": "finished",
- "title": "State",
- "type": "string"
-}Output schema / properties / statusAdded value: +{
+ "enum": [
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled",
+ "timed_out"
+ ],
+ "title": "Status",
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "invocation_id",
- "state",
- "result"
-]New value: +[
+ "invocation_id",
+ "status",
+ "reason",
+ "elapsed_ms"
+]Output schema / titlePrevious value: -"CancelAgentPayload"New value: +"InvocationPayload"describe_provider4 fields changedInput schema / properties / provider / descriptionPrevious value: -"Provider to describe before using start_agent."New value: +"Provider whose permitted status and options to return."Output schema / properties / defaultsRemoved value: -{
- "additionalProperties": {
- "type": "string"
- },
- "title": "Defaults",
- "type": "object"
-}Output schema / properties / guidanceRemoved value: -{
- "title": "Guidance",
- "type": "string"
-}Output schema / requiredPrevious value: -[
- "provider",
- "permitted",
- "defaults",
- "supported_options",
- "guidance"
-]New value: +[
+ "provider",
+ "permitted",
+ "supported_options"
+]start_agent20 fields changedInput schema / properties / provider / descriptionPrevious value: -"CLI requested by the user, not a model ID. Providers permitted by this host configuration: antigravity, claude, codebuddy, codex, grok. Excluded providers: none. Exclusions are enforced before an invocation is created. Choose an installed, authenticated permitted CLI; if none is available, report the blocker instead of falling back to an excluded provider."New value: +"CLI requested by the user, not a model ID. Providers permitted by this host configuration: antigravity, claude, codebuddy, codex, grok. Excluded providers: none. Excluded providers are rejected before launch."Input schema / properties / provider_options / descriptionPrevious value: -"Explicit options for the selected CLI. Call describe_provider(provider) for supported keys and model/effort defaults; user choices override those defaults."New value: +"Explicit options for the selected CLI. Call describe_provider(provider) for supported keys. Omitted options inherit native CLI settings."Input schema / properties / timeout_seconds / anyOfAdded value: +[
+ {
+ "exclusiveMinimum": 0,
+ "maximum": 86400,
+ "type": "number"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / timeout_seconds / defaultPrevious value: -1800New value: +nullInput schema / properties / timeout_seconds / descriptionPrevious value: -"Total runtime limit in seconds; expiry stops the invocation."New value: +"Optional total runtime limit in seconds; expiry stops the invocation. Omit or null for no AgentNave deadline; native CLI limits still apply."Input schema / properties / timeout_seconds / exclusiveMinimumRemoved value: -0Input schema / properties / timeout_seconds / maximumRemoved value: -86400Input schema / properties / timeout_seconds / typeRemoved value: -"number"Output schema / $defsAdded value: +{
+ "ActivityPayload": {
+ "properties": {
+ "age_ms": {
+ "title": "Age Ms",
+ "type": "integer"
+ },
+ "kind": {
+ "title": "Kind",
+ "type": "string"
+ },
+ "state": {
+ "title": "State",
+ "type": "string"
+ },
+ "tool_name": {
+ "title": "Tool Name",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "title": "ActivityPayload",
+ "type": "object"
+ },
+ "InvocationErrorPayload": {
+ "properties": {
+ "code": {
+ "title": "Code",
+ "type": "string"
+ },
+ "message": {
+ "title": "Message",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "title": "InvocationErrorPayload",
+ "type": "object"
+ }
+}Output schema / properties / activityAdded value: +{
+ "$ref": "#/$defs/ActivityPayload"
+}Output schema / properties / elapsed_msAdded value: +{
+ "title": "Elapsed Ms",
+ "type": "integer"
+}Output schema / properties / errorAdded value: +{
+ "$ref": "#/$defs/InvocationErrorPayload"
+}Output schema / properties / outputAdded value: +{
+ "title": "Output",
+ "type": "string"
+}Output schema / properties / output_age_msAdded value: +{
+ "title": "Output Age Ms",
+ "type": "integer"
+}Output schema / properties / reasonAdded value: +{
+ "enum": [
+ "started",
+ "wait_elapsed",
+ "execution_blocked",
+ "finished"
+ ],
+ "title": "Reason",
+ "type": "string"
+}Output schema / properties / session_idAdded value: +{
+ "title": "Session Id",
+ "type": "string"
+}Output schema / properties / stateRemoved value: -{
- "const": "running",
- "title": "State",
- "type": "string"
-}Output schema / properties / statusAdded value: +{
+ "enum": [
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled",
+ "timed_out"
+ ],
+ "title": "Status",
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "invocation_id",
- "state"
-]New value: +[
+ "invocation_id",
+ "status",
+ "reason",
+ "elapsed_ms"
+]Output schema / titlePrevious value: -"StartAgentPayload"New value: +"InvocationPayload"wait_agent24 fields changedInput schema / properties / wait_timeout_seconds / defaultPrevious value: -30New value: +600Input schema / properties / wait_timeout_seconds / maximumPrevious value: -300New value: +600Output schema / $defs / ActivityPayloadAdded value: +{
+ "properties": {
+ "age_ms": {
+ "title": "Age Ms",
+ "type": "integer"
+ },
+ "kind": {
+ "title": "Kind",
+ "type": "string"
+ },
+ "state": {
+ "title": "State",
+ "type": "string"
+ },
+ "tool_name": {
+ "title": "Tool Name",
+ "type": "string"
+ }
+ },
+ "required": [
+ "kind"
+ ],
+ "title": "ActivityPayload",
+ "type": "object"
+}Output schema / $defs / InvocationErrorPayload / properties / detailsRemoved value: -{
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Details"
-}Output schema / $defs / InvocationErrorPayload / requiredPrevious value: -[
- "code",
- "message",
- "details"
-]New value: +[
+ "code",
+ "message"
+]Output schema / $defs / InvocationPhaseNameRemoved value: -{
- "enum": [
- "preparing",
- "running",
- "stopping"
- ],
- "type": "string"
-}Output schema / $defs / InvocationResultPayloadRemoved value: -{
- "properties": {
- "duration_ms": {
- "title": "Duration Ms",
- "type": "integer"
- },
- "error": {
- "anyOf": [
- {
- "$ref": "#/$defs/InvocationErrorPayload"
- },
- {
- "type": "null"
- }
- ]
- },
- "output": {
- "title": "Output",
- "type": "string"
- },
- "provider": {
- "$ref": "#/$defs/ProviderName"
- },
- "provider_usage": {
- "$ref": "#/$defs/ProviderUsagePayload"
- },
- "session_id": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "title": "Session Id"
- },
- "status": {
- "$ref": "#/$defs/InvocationStatusName"
- }
- },
- "required": [
- "status",
- "provider",
- "output",
- "session_id",
- "provider_usage",
- "duration_ms",
- "error"
- ],
- "title": "InvocationResultPayload",
- "type": "object"
-}Output schema / $defs / InvocationSnapshotPayloadRemoved value: -{
- "properties": {
- "elapsed_ms": {
- "title": "Elapsed Ms",
- "type": "integer"
- },
- "last_event_age_ms": {
- "anyOf": [
- {
- "type": "integer"
- },
- {
- "type": "null"
- }
- ],
- "title": "Last Event Age Ms"
- },
- "phase": {
- "$ref": "#/$defs/InvocationPhaseName"
- }
- },
- "required": [
- "phase",
- "elapsed_ms",
- "last_event_age_ms"
- ],
- "title": "InvocationSnapshotPayload",
- "type": "object"
-}Output schema / $defs / InvocationStatusNameRemoved value: -{
- "enum": [
- "succeeded",
- "failed",
- "blocked",
- "cancelled",
- "timed_out"
- ],
- "type": "string"
-}Output schema / $defs / ProviderNameRemoved value: -{
- "enum": [
- "antigravity",
- "claude",
- "codebuddy",
- "codex",
- "grok"
- ],
- "type": "string"
-}Output schema / $defs / ProviderUsagePayloadRemoved value: -{
- "properties": {
- "num_turns": {
- "title": "Num Turns",
- "type": "integer"
- },
- "total_cost_usd": {
- "title": "Total Cost Usd",
- "type": "number"
- }
- },
- "title": "ProviderUsagePayload",
- "type": "object"
-}Output schema / properties / activityAdded value: +{
+ "$ref": "#/$defs/ActivityPayload"
+}Output schema / properties / elapsed_msAdded value: +{
+ "title": "Elapsed Ms",
+ "type": "integer"
+}Output schema / properties / errorAdded value: +{
+ "$ref": "#/$defs/InvocationErrorPayload"
+}Output schema / properties / outputAdded value: +{
+ "title": "Output",
+ "type": "string"
+}Output schema / properties / output_age_msAdded value: +{
+ "title": "Output Age Ms",
+ "type": "integer"
+}Output schema / properties / reasonAdded value: +{
+ "enum": [
+ "started",
+ "wait_elapsed",
+ "execution_blocked",
+ "finished"
+ ],
+ "title": "Reason",
+ "type": "string"
+}Output schema / properties / resultRemoved value: -{
- "$ref": "#/$defs/InvocationResultPayload"
-}Output schema / properties / session_idAdded value: +{
+ "title": "Session Id",
+ "type": "string"
+}Output schema / properties / snapshotRemoved value: -{
- "$ref": "#/$defs/InvocationSnapshotPayload"
-}Output schema / properties / stateRemoved value: -{
- "enum": [
- "running",
- "finished"
- ],
- "title": "State",
- "type": "string"
-}Output schema / properties / statusAdded value: +{
+ "enum": [
+ "running",
+ "succeeded",
+ "failed",
+ "blocked",
+ "cancelled",
+ "timed_out"
+ ],
+ "title": "Status",
+ "type": "string"
+}Output schema / requiredPrevious value: -[
- "invocation_id",
- "state"
-]New value: +[
+ "invocation_id",
+ "status",
+ "reason",
+ "elapsed_ms"
+]Output schema / titlePrevious value: -"WaitAgentPayload"New value: +"InvocationPayload"v0.5.0describe_providerstart_agent5 fields changedInput schema / properties / prompt / descriptionPrevious value: -"Complete, self-contained task for the subagent."New value: +"Complete task, context, constraints, and expected output; the CLI does not inherit this conversation."Input schema / properties / provider / descriptionPrevious value: -"Local subagent provider to launch."New value: +"CLI requested by the user, not a model ID. Providers permitted by this host configuration: antigravity, claude, codebuddy, codex, grok. Excluded providers: none. Exclusions are enforced before an invocation is created. Choose an installed, authenticated permitted CLI; if none is available, report the blocker instead of falling back to an excluded provider."Input schema / properties / provider_options / descriptionPrevious value: -"Explicit provider-native options. Omit to inherit the provider's own settings; supported keys depend on the selected provider."New value: +"Explicit options for the selected CLI. Call describe_provider(provider) for supported keys and model/effort defaults; user choices override those defaults."Input schema / properties / session_id / descriptionPrevious value: -"Provider session ID returned by an earlier finished invocation."New value: +"To continue a conversation, use the session_id returned by a finished invocation of the same provider; omit for a new conversation. Never use an invocation_id here."Input schema / properties / timeout_seconds / descriptionPrevious value: -"Maximum provider runtime in seconds."New value: +"Total runtime limit in seconds; expiry stops the invocation."wait_agent1 field changedInput schema / properties / wait_timeout_seconds / descriptionPrevious value: -"Maximum time to wait during this call, in seconds."New value: +"Seconds to wait for this response; expiry leaves the invocation running."v0.3.0cancel_agent1 field changedOutput schema / $defs / ProviderName / enumPrevious value: -[
- "antigravity",
- "claude",
- "codebuddy",
- "grok"
-]New value: +[
+ "antigravity",
+ "claude",
+ "codebuddy",
+ "codex",
+ "grok"
+]start_agent1 field changedInput schema / $defs / ProviderName / enumPrevious value: -[
- "antigravity",
- "claude",
- "codebuddy",
- "grok"
-]New value: +[
+ "antigravity",
+ "claude",
+ "codebuddy",
+ "codex",
+ "grok"
+]wait_agent1 field changedOutput schema / $defs / ProviderName / enumPrevious value: -[
- "antigravity",
- "claude",
- "codebuddy",
- "grok"
-]New value: +[
+ "antigravity",
+ "claude",
+ "codebuddy",
+ "codex",
+ "grok"
+]v0.2.0cancel_agentstart_agentwait_agentScored across 4 tools
Each tool has a distinct lifecycle role: start_agent launches, wait_agent observes, cancel_agent stops, and describe_provider inspects provider configuration. There is no meaningful overlap between any two tools.
Three tools follow the verb_agent pattern (start_agent, wait_agent, cancel_agent), while describe_provider uses a different object. The imperative verb_noun style is consistent and readable, with only a minor deviation.
Four tools is well-scoped for an agent lifecycle management server. Each tool covers a necessary operation without redundancy or unnecessary surface area.
The core lifecycle is covered: start, wait, cancel, and provider capability discovery. A dedicated listing/status tool is absent, but wait_agent and cancel_agent can retrieve state by ID, so agents can work around that minor gap.
Agent-native launch platform and tool directory: search, alternatives, trending, launch via MCP.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage