Use the Hermes Public Subagent Lifecycle API Safely

Plugin authors can launch and supervise fresh Hermes child sessions through the public subagent lifecycle service instead of importing delegate-tool, gateway, TUI, or internal agent state. The service resolves the parent from the active turn and fails closed when no active Hermes parent session exists.

Lifecycle contract

A launch request carries a goal, context, role, optional correlation metadata, and an optional list of allowed toolsets. The returned handle is serializable and contains a versioned opaque capability. Pass that handle back to status, wait, cancel, result, or reconnect. Forged or malformed handles return an unknown state rather than exposing another child.

Stable states distinguish pending, starting, running, success, failure, interruption, requested cancellation, completed cancellation, and unknown. Cancellation is cooperative: a request changes the state to CANCEL_REQUESTED, but callers must wait for a terminal observation before claiming the child stopped.

Integration checklist

Call the service only from a plugin tool or hook during an active agent turn.
Write a self-contained goal and bounded context.
Narrow allowed_toolsets beneath the parent’s authority.
Store the serialized handle only when later supervision is needed.
Poll or wait with a bounded timeout instead of blocking the parent indefinitely.
Treat cancellation as requested until a terminal state is observed.
Verify terminal result status and stable result hash.
Design for in-process retention and process-exit interruption.
Keep transcripts and hidden reasoning out of plugin persistence.

Isolation and limits

Requests cannot broaden the parent’s tool authority. Unknown or broader toolsets fail closed, and the existing unsafe-tool block remains active. The initial API also rejects per-tool blocks, working-directory overrides, and per-launch timeouts rather than pretending to isolate features it cannot yet enforce safely.

Terminal results are immutable, idempotent, bounded, and omit transcripts and hidden reasoning. Metadata and terminal results are retained in process for a limited window. Threads do not survive process exit; reconnect after restart reports that reconnection is unavailable and does not silently launch a replacement child.

Common pitfalls

Calling the lifecycle service outside an active turn.
Giving a child a vague goal that depends on the parent’s unstated conversation.
Requesting toolsets broader than the parent owns.
Reporting CANCEL_REQUESTED as CANCELLED.
Assuming a persisted handle survives a Hermes process restart.
Launching a replacement automatically after reconnect fails and duplicating side effects.
Persisting child transcripts or hidden reasoning outside the service contract.
Holding the parent turn open forever instead of returning a handle for later supervision.

Verification steps

Launch a read-only test child with only the file toolset and confirm the handle serializes.
Query status through normal state transitions and wait with a short timeout.
Retrieve the terminal result twice and confirm it is immutable and hash-stable.
Submit a forged handle and verify it returns unknown without data.
Request a parent-broadening toolset and verify launch fails closed.
Cancel a long-running test child and confirm requested cancellation becomes a terminal state before reporting completion.
Restart a test process and confirm reconnect returns unavailable without launching a replacement.

Official documentation

https://hermes-agent.nousresearch.com/docs/developer-guide/subagent-lifecycle-api