# Subagent daemon

`hive-subagent-daemon` (crate `hive-subagent-mcp`) spawns nested headless
`claude` sessions on request. Own process, own systemd unit, own MCP
server (`subagent`, not `hyperhive`) — independent of `hive-bash-daemon`:
a subagent is a full nested claude process, a materially heavier
capability than a background shell command, so it gets its own
deployable/restartable unit rather than living inside the bash daemon.

Shipped default-on for every agent — `nix/agent-modules/mcp.nix` injects
`subagent` into `hyperhive.extraMcpServers` unconditionally (`allowedTools
= ["*"]`), same as `bash`. The operator's own framing: default-on for
now, a real opt-in capability later.

For what the tools do and when an agent should reach for them, see the
`subagent` MCP server's own tool descriptions and the
`base:claude-subagents` skill — this page covers the daemon as deployed
infrastructure, not the agent-facing API.

## Tools

Served under the `subagent` MCP server (`mcp__subagent__<tool>`): `start`,
`continue`, `status`, `interrupt`.

## State

In-memory only: a map of currently-running processes, live only as long
as the daemon process is. A daemon restart stops whatever was running
rather than adopting it. The durable record of a subagent's existence is
claude's own on-disk session (`hive_claude::SessionStore`), which
`continue` reattaches to independent of the daemon's own lifetime — a
restart loses the _in-flight turn_, not the subagent's history.

## Compaction trade-off

Built on `hive_claude::Claude::spawn` + `RunningClaude::wait` directly
rather than `InfiniteSession::run`, since only the low-level driver
exposes a cancel handle to stop a turn mid-flight — that's what makes
`interrupt` genuinely stop a running turn rather than only cancelling a
still-pending one. The cost: a turn that overflows the context window
surfaces as an error rather than self-healing via reactive compaction.
Subagents are meant to be bounded, single-batch work, not sessions
long-lived enough to need in-place compaction — a real follow-up if that
assumption stops holding.

## Configuration

`hyperhive.mcp.subagentHttpPort` — the daemon's streamable-http listen
port. Same pattern as `bashHttpPort`/`matrixHttpPort`: a per-agent default
assigned by `nix/agent-modules/mcp.nix`, only worth overriding for an
agent that needs a stable or non-default port.

Own systemd unit, defined alongside the other per-agent MCP daemons in
`nix/agent-modules/mcp.nix`.