hive

Overview Schema Source Related Servers Discussions Admin

agent_close

DestructiveIdempotent

Close an agent's tmux window and mark it closed, capturing handoffs before termination. Target by name or agent_id; self-close needs confirmation; row-only retires stale rows.

Instructions

Kill an agent's tmux window and mark it closed, addressed by name (or agent_id). Capture handoffs (todo comments, pads) BEFORE closing; terminal output is not retained. Closing yourself requires confirm_self=true. Refuses a lead target whose pane is live; retires one whose pane is confirmed dead. A worker may never close a lead, live or dead. row_only=true retires a stale row with no kill, stop or typing: for a human or peer lead only, and refused for any row that provably owns a live pane or when tmux could not be probed.

Input Schema

TableJSON Schema

Name	Required	Description
`name`	No	The worker's name, e.g. "impl" or "DEVX-123". Prefer passing this rather than agent_id, but pass only one: if both arrive, agent_id wins and this is ignored. A partial name works when it matches exactly one running worker, so "123" finds DEVX-123.
`agent_id`	No	Numeric agent id. Use name instead unless you have the id to hand.
`row_only`	No	Mark the row closed with no kill, stop or typing, for a row whose pane is gone, reissued or unverifiable. Human or peer lead only. Defaults to false.
`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.
`confirm_self`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`name`	Yes
`note`	No
`closed`	Yes
`parked`	No
`agent_id`	Yes
`row_only`	No
`hive_notice`	No
`park_released`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.6.0Oct 3, 2026

addedInput schema / properties / row_only

Added value: +{
+  "description": "Mark the row closed with no kill, stop or typing, for a row whose pane is gone, reissued or unverifiable. Human or peer lead only. Defaults to false.",
+  "type": "boolean"
+}

addedOutput schema / properties / row_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.8/5.0

Behavior5/5

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

Goes well beyond the destructiveHint/idempotentHint annotations: terminal output is not retained, handoffs must be captured first, live lead panes are refused, dead ones retired, and row_only is refused when a live pane is provably owned or tmux could not be probed. These are non-obvious behavioral guards an agent could not infer from annotations alone.

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 the critical handoff warning before the guard clauses. Dense and semicolon-heavy, but nearly every clause carries operational information; only slight trimming would be possible.

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 a destructive, multi-guard tool, the description covers the mutation, the irreversible loss (terminal output), the permission model (leads vs workers), and the edge-case escape hatch (row_only). An output schema exists, so return values need no elaboration.

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 80%, so the baseline is 3, but the description adds real semantic meaning for row_only (the exact refusal conditions) and confirm_self (required only when closing yourself), plus the precedence rule that agent_id wins over name.

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

Purpose5/5

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

States a specific verb+resource: kill an agent's tmux window and mark it closed, addressed by name or agent_id. This is clearly distinguishable from siblings like agent_park, agent_resume, and agent_spawn.

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

Usage Guidelines5/5

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

Explicit when/when-not guidance: capture handoffs before closing, confirm_self=true required to close yourself, refuses a live lead target but retires a dead one, and a worker may never close a lead. row_only usage is scoped precisely to human or peer leads.

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