hive

Overview Schema Source Related Servers Discussions Admin

agent_spawn

Spawn a project-locked worker agent in a tmux pane or window to delegate assignments, with automatic briefing, harness selection, and optional read-only enforcement.

Instructions

Spawn a worker agent (default: claude, or the project's hive.yml agents: default). A claude worker is briefed automatically: the full brief is appended to its system prompt, so send it its assignment directly. A command or harness that resolves to a known harness (claude, codex) not listed in the project's hive.yml agents: is refused; absent agents: means claude only. A command hive cannot classify the screen of (claude and codex both do; a harness with no entry does not) can be spawned but NOT typed into: the receipt carries brief_path and says so, and agent_send's text path and wakes both refuse that pane. A same-project worker or lead on that harness's active usage limit makes this spawn retryable until its reset or bounded deadline; hive does not queue spawns. Set read_only: true to block local file writes and mutating shell while keeping Hive MCP available; agent_resume preserves this mode and agent_status reports it. Only bare claude/codex executables are supported in this mode, with only effort-setting extra_args. The worker is locked to this project. Humans can watch with: tmux attach -t hive-main.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "agent_spawn"
  }
}

Input Schema

Name	Required	Description
`cwd`	No	Working directory, e.g. a git worktree path. Defaults to the project root.
`name`	No	Display name; defaults to worker-N. This is how you address the worker later.
`model`	No	Passed as --model to the agent command.
`layout`	No	How to arrange the lead's window when placement is split. main-vertical gives the lead the left half with workers stacked on the right; tiled (default) splits evenly. Projects can set a default in hive.yml.
`command`	No	Raw agent command to run. Overrides harness when both are given. Defaults to the project's hive.yml agents: default, or claude. Refused if it resolves to a known harness the project's agents: list does not allow.
`harness`	No	Spawn a known harness by name (e.g. "codex") instead of a raw command. Ignored when command is also given. Must be in the project's hive.yml agents: list (default: claude only).
`todo_id`	No	The todo this worker is on, recorded as a link (a non-archived todo in the same project). Changes no todo status.
`placement`	No	Omit this to use the project's hive.yml placement, else HIVE_SPAWN_PLACEMENT, else split. split: the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode). agent_output reads scrollback, so a crowded window does not limit what a lead can read. If workers end up in other windows, run hive layout to gather them.
`read_only`	No	Prevent local file writes and mutating shell commands while allowing Hive MCP tools. Only bare claude/codex executables. Extra args allow codex -c model_reasoning_effort=low\|medium\|high\|xhigh, or claude --effort low\|medium\|high\|xhigh\|max; all other arguments are refused.
`extra_args`	No	Extra CLI arguments.
`project_id`	No	Different project override. Use ONLY when the user explicitly asks for another project by name; otherwise stay in the current scope, even when results are empty.

Output Schema

Name	Required	Description	Default
`name`	Yes
`note`	No
`tail`	No
`ready`	No
`exited`	No
`layout`	No
`actor_id`	Yes
`agent_id`	Yes
`read_only`	No
`brief_path`	No
`codex_home`	No
`hive_notice`	No
`tmux_target`	Yes
`instructions`	No
`config_warnings`	No
`worktree_install`	No
`landed_in_project`	No
`codex_instructions`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.12.0Nov 3, 2026

changedInput schema / properties / placement / description

Previous value: -"split (default): the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode)."New value: +"Omit this to use the project's hive.yml placement, else HIVE_SPAWN_PLACEMENT, else split. split: the worker appears as a pane in the lead's window, auto-tiled, so the whole crew shares one screen. window: its own tmux window (an iTerm tab under control mode). agent_output reads scrollback, so a crowded window does not limit what a lead can read. If workers end up in other windows, run hive layout to gather them."

Changed1 schema field changedv1.11.5Oct 15, 2026

addedInput schema / properties / todo_id

Added value: +{
+  "description": "The todo this worker is on, recorded as a link (a non-archived todo in the same project). Changes no todo status.",
+  "exclusiveMinimum": 0,
+  "maximum": 9007199254740991,
+  "type": "integer"
+}

Changed2 schema fields changedv1.4.0Sep 30, 2026

addedInput schema / properties / read_only

Added value: +{
+  "description": "Prevent local file writes and mutating shell commands while allowing Hive MCP tools. Only bare claude/codex executables. Extra args allow codex -c model_reasoning_effort=low|medium|high|xhigh, or claude --effort low|medium|high|xhigh|max; all other arguments are refused.",
+  "type": "boolean"
+}

addedOutput schema / properties / read_only
```
Added value: +{
+  "type": "boolean"
+}
```

Changed1 schema field changedv1.2.2Sep 26, 2026
- addedOutput schema / properties / hive_notice
```
Added value: +{
+  "type": "string"
+}
```
First observedv1.0.0Sep 22, 2026

TDQS

A4.3/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations: briefs are auto-appended to the system prompt, unclassifiable harnesses spawn but cannot be typed into, the receipt carries brief_path, usage-limit spawns are retryable and never queued, read_only mode persists across agent_resume and is reported by agent_status, and the worker is locked to the project. This is exactly the extra operational context annotations can't express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and then ordered by importance (briefing, refusal rules, retryability, read_only). It is dense and heavily parenthetical, with some overlap between the read_only sentence and the schema text, but nearly every clause carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter spawn tool with a real output schema, the description covers the failure modes (refusal, retryable spawns), the read_only constraints, and the project lock. Combined with the output schema and 100% param coverage, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics: command overrides harness, read_only restricts extra_args to effort settings only, and project_id is a narrow escape hatch. These interactions and constraints add real meaning beyond the individual field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a concrete verb+resource: 'Spawn a worker agent' plus the default harness resolution rule. It's immediately clear this creates a new agent rather than messaging or resuming one. It doesn't explicitly contrast against agent_fork or agent_resume, so it falls short of a 5 on sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides several concrete usage conditions: harness refusal rules, when spawns are retryable, and 'Set read_only: true to block local file writes' — plus a strong scoping rule for project_id ('Use ONLY when the user explicitly asks'). Lacks an explicit 'use this instead of X' statement against agent_fork, keeping it below 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.